@downcity/agent 1.1.1

package/src/model/ModelManager.ts

@@ -0,0 +1,242 @@
+/**
+ * ModelManager：LLM 模型预设管理器。
+ *
+ * 关键点（中文）
+ * - 统一管理 init 场景的“模型预设清单 + providerType 映射 + 自定义模型标记”。
+ * - 避免命令层直接依赖硬编码常量，提升可维护性与一致性。
+ */
+
+import type { LlmProviderType } from "@/shared/types/LlmConfig.js";
+
+/**
+ * 单个模型预设定义。
+ */
+export type ModelPreset = {
+  /**
+   * 预设 ID（同时作为模型名称写入 `llm.models.<active>.name`，除自定义模型外）。
+   */
+  id: string;
+
+  /**
+   * 预设标题（用于 CLI 交互显示）。
+   */
+  title: string;
+
+  /**
+   * 对应 provider 类型（用于生成 `llm.providers.<id>.type`）。
+   */
+  providerTypes: readonly LlmProviderType[];
+
+  /**
+   * 是否属于“模型名由环境变量注入”的自定义模型类型。
+   */
+  useCustomModelName: boolean;
+};
+
+const CUSTOM_MODEL_IDS = new Set<string>(["open-compatible", "open-responses"]);
+
+const MODEL_PRESETS: ModelPreset[] = [
+  // Claude 系列
+  {
+    id: "claude-sonnet-4-5",
+    title: "Claude Sonnet 4",
+    providerTypes: ["anthropic"],
+    useCustomModelName: false,
+  },
+  {
+    id: "claude-haiku",
+    title: "Claude Haiku",
+    providerTypes: ["anthropic"],
+    useCustomModelName: false,
+  },
+  {
+    id: "claude-3-5-sonnet-20241022",
+    title: "Claude 3.5 Sonnet",
+    providerTypes: ["anthropic"],
+    useCustomModelName: false,
+  },
+  {
+    id: "claude-3-opus-20240229",
+    title: "Claude 3 Opus",
+    providerTypes: ["anthropic"],
+    useCustomModelName: false,
+  },
+  // OpenAI GPT 系列
+  {
+    id: "gpt-4",
+    title: "GPT-4",
+    providerTypes: ["openai"],
+    useCustomModelName: false,
+  },
+  {
+    id: "gpt-4-turbo",
+    title: "GPT-4 Turbo",
+    providerTypes: ["openai"],
+    useCustomModelName: false,
+  },
+  {
+    id: "gpt-4o",
+    title: "GPT-4o",
+    providerTypes: ["openai"],
+    useCustomModelName: false,
+  },
+  {
+    id: "gpt-3.5-turbo",
+    title: "GPT-3.5 Turbo",
+    providerTypes: ["openai"],
+    useCustomModelName: false,
+  },
+  // DeepSeek
+  {
+    id: "deepseek-chat",
+    title: "DeepSeek Chat",
+    providerTypes: ["deepseek"],
+    useCustomModelName: false,
+  },
+  // Gemini
+  {
+    id: "gemini-2.5-pro",
+    title: "Gemini 2.5 Pro",
+    providerTypes: ["gemini"],
+    useCustomModelName: false,
+  },
+  {
+    id: "gemini-2.5-flash",
+    title: "Gemini 2.5 Flash",
+    providerTypes: ["gemini"],
+    useCustomModelName: false,
+  },
+  // xAI
+  {
+    id: "grok-3",
+    title: "xAI Grok 3",
+    providerTypes: ["xai"],
+    useCustomModelName: false,
+  },
+  // HuggingFace Router
+  {
+    id: "meta-llama/Llama-3.1-8B-Instruct",
+    title: "HF Llama 3.1 8B",
+    providerTypes: ["huggingface"],
+    useCustomModelName: false,
+  },
+  // OpenRouter
+  {
+    id: "openrouter/auto",
+    title: "OpenRouter Auto",
+    providerTypes: ["openrouter"],
+    useCustomModelName: false,
+  },
+  // Moonshot(Kimi)
+  {
+    id: "kimi-k2.5",
+    title: "Kimi K2.5",
+    providerTypes: ["moonshot-cn", "moonshot-ai"],
+    useCustomModelName: false,
+  },
+  {
+    id: "kimi-for-coding",
+    title: "Kimi For Coding",
+    providerTypes: ["kimi-code"],
+    useCustomModelName: false,
+  },
+  // OpenAI-compatible（Chat Completions）
+  {
+    id: "open-compatible",
+    title: "Open-compatible model",
+    providerTypes: ["open-compatible"],
+    useCustomModelName: true,
+  },
+  // OpenAI-compatible（Responses）
+  {
+    id: "open-responses",
+    title: "Open-responses model",
+    providerTypes: ["open-responses"],
+    useCustomModelName: true,
+  },
+];
+
+const DEFAULT_MODEL_PRESET_ID = "claude-sonnet-4-5";
+const FALLBACK_MODEL_PRESET_ID = "open-compatible";
+
+/**
+ * init 模型选择解析结果。
+ */
+export type ResolvedInitModelPreset = {
+  /**
+   * 规范化后的模型预设 ID。
+   */
+  selectedModelId: string;
+
+  /**
+   * 选中的模型预设。
+   */
+  preset: ModelPreset;
+};
+
+/**
+ * 模型预设管理器。
+ */
+export class ModelManager {
+  private readonly presets: ModelPreset[];
+  private readonly presetsById: Map<string, ModelPreset>;
+
+  constructor() {
+    this.presets = [...MODEL_PRESETS];
+    this.presetsById = new Map(
+      this.presets.map((preset) => [preset.id, preset] as const),
+    );
+  }
+
+  /**
+   * 列出所有可选模型预设（按定义顺序）。
+   */
+  listPresets(): ModelPreset[] {
+    return [...this.presets];
+  }
+
+  /**
+   * 根据预设 ID 获取模型预设。
+   */
+  getPreset(id: string): ModelPreset | undefined {
+    const key = String(id || "").trim();
+    if (!key) return undefined;
+    return this.presetsById.get(key);
+  }
+
+  /**
+   * 判断预设是否支持指定 provider 类型。
+   */
+  supportsProviderType(preset: ModelPreset, providerType: LlmProviderType): boolean {
+    return preset.providerTypes.includes(providerType);
+  }
+
+  /**
+   * 获取默认模型预设。
+   */
+  getDefaultPreset(): ModelPreset {
+    return (
+      this.getPreset(DEFAULT_MODEL_PRESET_ID) ||
+      this.getPreset(FALLBACK_MODEL_PRESET_ID) ||
+      this.presets[0]
+    );
+  }
+
+  /**
+   * 解析 init 输入的模型选择，并返回稳定的预设结果。
+   */
+  resolveInitPreset(input?: string): ResolvedInitModelPreset {
+    const selectedModelId = String(input || "").trim();
+    const preset =
+      this.getPreset(selectedModelId) ||
+      this.getPreset(FALLBACK_MODEL_PRESET_ID) ||
+      this.getDefaultPreset();
+    return {
+      selectedModelId: selectedModelId || preset.id,
+      preset: {
+        ...preset,
+        useCustomModelName: CUSTOM_MODEL_IDS.has(preset.id),
+      },
+    };
+  }
+}

package/src/plugin/Activation.ts

@@ -0,0 +1,22 @@
+/**
+ * Plugin 激活判定工具。
+ *
+ * 关键点（中文）
+ * - 统一收敛“某个 plugin 在当前 city 配置下是否启用”的规则。
+ * - plugin 启用态属于 city 级生命周期配置，不再来自 agent `downcity.json`。
+ */
+
+import type { Plugin } from "@/shared/types/Plugin.js";
+import { isCityPluginEnabled } from "@/plugin/Lifecycle.js";
+
+/**
+ * 读取当前 city 配置下的 plugin 启用态。
+ */
+export function isPluginEnabled(params: {
+  plugin: Plugin;
+}): boolean {
+  const pluginName = String(params.plugin.name || "").trim();
+  if (!pluginName) return false;
+  if (pluginName === "auth") return true;
+  return isCityPluginEnabled(pluginName);
+}

package/src/plugin/Catalog.ts

@@ -0,0 +1,118 @@
+/**
+ * Plugin Catalog。
+ *
+ * 关键点（中文）
+ * - 这里承载 console 侧的静态 plugin 元数据视图。
+ * - 目标是把“控制面可见的 plugin 定义”从 agent 执行态里拆出来复用。
+ * - 当前先服务 Console 与 `city plugin` CLI 的静态回退场景。
+ */
+
+import { PLUGINS } from "@/plugin/Plugins.js";
+import { isPluginEnabled } from "@/plugin/Activation.js";
+import type {
+  Plugin,
+  PluginAvailability,
+  PluginView,
+} from "@/shared/types/Plugin.js";
+
+/**
+ * 将 Plugin 定义转换成静态概览视图。
+ */
+export function toStaticPluginView(plugin: Plugin): PluginView {
+  return {
+    name: plugin.name,
+    title: String(plugin.title || plugin.name || "").trim(),
+    description: String(plugin.description || "").trim(),
+    actions: Object.keys(plugin.actions || {}).sort((a, b) => a.localeCompare(b)),
+    pipelines: Object.keys(plugin.hooks?.pipeline || {}).sort((a, b) =>
+      a.localeCompare(b),
+    ),
+    guards: Object.keys(plugin.hooks?.guard || {}).sort((a, b) =>
+      a.localeCompare(b),
+    ),
+    effects: Object.keys(plugin.hooks?.effect || {}).sort((a, b) =>
+      a.localeCompare(b),
+    ),
+    resolves: Object.keys(plugin.resolves || {}).sort((a, b) =>
+      a.localeCompare(b),
+    ),
+    hasSystem: typeof plugin.system === "function",
+    hasAvailability: typeof plugin.availability === "function",
+  };
+}
+
+/**
+ * 列出全部内建 plugin 定义。
+ */
+export function listBuiltinPlugins(): Plugin[] {
+  return [...PLUGINS];
+}
+
+/**
+ * 列出全部内建 plugin 的静态概览视图。
+ */
+export function listStaticPluginViews(): PluginView[] {
+  return listBuiltinPlugins()
+    .map((plugin) => toStaticPluginView(plugin))
+    .sort((a, b) => a.name.localeCompare(b.name));
+}
+
+/**
+ * 按名称查找内建 plugin 定义。
+ */
+export function findBuiltinPlugin(pluginName: string): Plugin | null {
+  const key = String(pluginName || "").trim();
+  if (!key) return null;
+  return listBuiltinPlugins().find((plugin) => plugin.name === key) || null;
+}
+
+/**
+ * 按名称查找内建 plugin 的静态概览视图。
+ */
+export function findStaticPluginView(
+  pluginName: string,
+): PluginView | null {
+  const plugin = findBuiltinPlugin(pluginName);
+  return plugin ? toStaticPluginView(plugin) : null;
+}
+
+/**
+ * 构建静态 plugin 可用性视图。
+ *
+ * 关键点（中文）
+ * - 这里表达的是“控制面视角下可见的 city 配置事实”，不是执行链路中的最终可用性。
+ * - `enabled` 只对齐 city 级 plugin lifecycle，不再读取 agent 项目配置。
+ * - `available` 仅在无需执行上下文即可明确判断为 false 时返回 false；否则静态层视为可用。
+ */
+export function buildStaticPluginAvailability(params: {
+  pluginName: string;
+  agentError?: string;
+}): PluginAvailability {
+  const plugin = findBuiltinPlugin(params.pluginName);
+  if (!plugin) {
+    return {
+      enabled: false,
+      available: false,
+      reasons: [`Unknown plugin: ${params.pluginName}`],
+    };
+  }
+
+  const enabled = isPluginEnabled({ plugin });
+
+  if (!enabled) {
+    return {
+      enabled: false,
+      available: false,
+      reasons: [`Plugin "${plugin.name}" is disabled in city config.`],
+    };
+  }
+
+  const agentReason = String(params.agentError || "").trim();
+  return {
+    enabled: true,
+    available: false,
+    reasons: agentReason
+      ? [`Agent server unavailable: ${agentReason}`]
+      : ["Static catalog view only. Agent-side availability is not loaded."],
+  };
+}

package/src/plugin/HookRegistry.ts

@@ -0,0 +1,249 @@
+/**
+ * Plugin 点注册表。
+ *
+ * 关键点（中文）
+ * - 统一管理 pipeline / guard / effect / resolve 四类 plugin 点。
+ * - service 只依赖固定执行语义，不再自己拼装扩展调度逻辑。
+ */
+
+import type { JsonValue } from "@/shared/types/Json.js";
+import type {
+  PluginEffectHook,
+  PluginGuardHook,
+  PluginPipelineHook,
+  PluginResolveHook,
+} from "@/shared/types/Plugin.js";
+import type { AgentContext } from "@/types/agent/AgentContext.js";
+
+type ContextResolver = () => AgentContext;
+type PluginEnabledChecker = (pluginName: string, context: AgentContext) => boolean;
+
+type PipelineRecord = {
+  pluginName: string;
+  handler: PluginPipelineHook<JsonValue>;
+};
+
+type GuardRecord = {
+  pluginName: string;
+  handler: PluginGuardHook<JsonValue>;
+};
+
+type EffectRecord = {
+  pluginName: string;
+  handler: PluginEffectHook<JsonValue>;
+};
+
+type ResolveRecord = {
+  pluginName: string;
+  handler: PluginResolveHook<JsonValue, JsonValue>;
+};
+
+/**
+ * HookRegistry：plugin 点注册与执行实现。
+ */
+export class HookRegistry {
+  private readonly contextResolver: ContextResolver;
+  private readonly pluginEnabledChecker: PluginEnabledChecker;
+
+  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: {
+    contextResolver: ContextResolver;
+    pluginEnabledChecker: PluginEnabledChecker;
+  }) {
+    this.contextResolver = params.contextResolver;
+    this.pluginEnabledChecker = params.pluginEnabledChecker;
+  }
+
+  /**
+   * 注册 pipeline 扩展点。
+   */
+  pipeline(
+    pointName: string,
+    pluginName: string,
+    handler: PluginPipelineHook<JsonValue>,
+  ): void {
+    const key = String(pointName || "").trim();
+    if (!key) {
+      throw new Error("Pipeline point name is required");
+    }
+    const bucket = this.pipelineHooks.get(key) || [];
+    bucket.push({
+      pluginName: String(pluginName || "").trim(),
+      handler,
+    });
+    this.pipelineHooks.set(key, bucket);
+  }
+
+  /**
+   * 注册 guard 扩展点。
+   */
+  guard(
+    pointName: string,
+    pluginName: string,
+    handler: PluginGuardHook<JsonValue>,
+  ): void {
+    const key = String(pointName || "").trim();
+    if (!key) {
+      throw new Error("Guard point name is required");
+    }
+    const bucket = this.guardHooks.get(key) || [];
+    bucket.push({
+      pluginName: String(pluginName || "").trim(),
+      handler,
+    });
+    this.guardHooks.set(key, bucket);
+  }
+
+  /**
+   * 注册 effect 扩展点。
+   */
+  effect(
+    pointName: string,
+    pluginName: string,
+    handler: PluginEffectHook<JsonValue>,
+  ): void {
+    const key = String(pointName || "").trim();
+    if (!key) {
+      throw new Error("Effect point name is required");
+    }
+    const bucket = this.effectHooks.get(key) || [];
+    bucket.push({
+      pluginName: String(pluginName || "").trim(),
+      handler,
+    });
+    this.effectHooks.set(key, bucket);
+  }
+
+  /**
+   * 注册 resolve 扩展点。
+   *
+   * 关键点（中文）
+   * - resolve 语义要求单点单处理器，避免 service 侧再做二次仲裁。
+   */
+  resolve(
+    pointName: string,
+    pluginName: string,
+    handler: PluginResolveHook<JsonValue, JsonValue>,
+  ): void {
+    const key = String(pointName || "").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, {
+      pluginName: String(pluginName || "").trim(),
+      handler,
+    });
+  }
+
+  /**
+   * 列出所有已注册扩展点。
+   */
+  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>(pointName: string, value: T): Promise<T> {
+    const key = String(pointName || "").trim();
+    if (!key) return value;
+    const bucket = this.pipelineHooks.get(key) || [];
+    if (bucket.length === 0) return value;
+
+    const context = this.contextResolver();
+    let current = value as JsonValue;
+    for (const item of bucket) {
+      if (!this.pluginEnabledChecker(item.pluginName, context)) continue;
+      current = await item.handler({
+        context,
+        value: current,
+        plugin: item.pluginName,
+      });
+    }
+    return current as T;
+  }
+
+  /**
+   * 运行 guard 扩展点。
+   */
+  async guardValue<T = JsonValue>(pointName: string, value: T): Promise<void> {
+    const key = String(pointName || "").trim();
+    if (!key) return;
+    const bucket = this.guardHooks.get(key) || [];
+    if (bucket.length === 0) return;
+
+    const context = this.contextResolver();
+    for (const item of bucket) {
+      if (!this.pluginEnabledChecker(item.pluginName, context)) continue;
+      await item.handler({
+        context,
+        value: value as JsonValue,
+        plugin: item.pluginName,
+      });
+    }
+  }
+
+  /**
+   * 运行 effect 扩展点。
+   */
+  async effectValue<T = JsonValue>(pointName: string, value: T): Promise<void> {
+    const key = String(pointName || "").trim();
+    if (!key) return;
+    const bucket = this.effectHooks.get(key) || [];
+    if (bucket.length === 0) return;
+
+    const context = this.contextResolver();
+    for (const item of bucket) {
+      if (!this.pluginEnabledChecker(item.pluginName, context)) continue;
+      await item.handler({
+        context,
+        value: value as JsonValue,
+        plugin: item.pluginName,
+      });
+    }
+  }
+
+  /**
+   * 运行 resolve 点。
+   */
+  async resolveValue<TInput = JsonValue, TOutput = JsonValue>(
+    pointName: string,
+    value: TInput,
+  ): Promise<TOutput> {
+    const key = String(pointName || "").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}`);
+    }
+    const context = this.contextResolver();
+    if (!this.pluginEnabledChecker(record.pluginName, context)) {
+      throw new Error(`No active plugin resolver registered for point: ${key}`);
+    }
+
+    return await record.handler({
+      context,
+      value: value as JsonValue,
+      plugin: record.pluginName,
+    }) as TOutput;
+  }
+}

package/src/plugin/HttpRoutes.ts

@@ -0,0 +1,50 @@
+/**
+ * Plugin HTTP 路由装配。
+ *
+ * 关键点（中文）
+ * - 这里统一装配内建 plugin 的 runtime HTTP 路由与鉴权策略。
+ * - plugin 自己声明路由；server 与 console 只负责消费这份声明。
+ */
+
+import type { Hono } from "hono";
+import { PLUGINS } from "@/plugin/Plugins.js";
+import type { AgentContext } from "@/types/agent/AgentContext.js";
+import type { AuthRoutePolicy } from "@/shared/types/auth/AuthRoute.js";
+
+function dedupeAuthPolicies(policies: AuthRoutePolicy[]): AuthRoutePolicy[] {
+  const records = new Map<string, AuthRoutePolicy>();
+
+  for (const policy of policies) {
+    const key = `${String(policy.method || "*").trim().toUpperCase()}:${String(policy.path || "").trim()}`;
+    if (!key.endsWith(":")) {
+      records.set(key, policy);
+    }
+  }
+
+  return [...records.values()];
+}
+
+/**
+ * 列出全部内建 plugin runtime 鉴权策略。
+ */
+export function listBuiltinPluginRuntimeAuthPolicies(): AuthRoutePolicy[] {
+  return dedupeAuthPolicies(
+    PLUGINS.flatMap((plugin) => plugin.http?.runtime?.authPolicies || []),
+  );
+}
+
+/**
+ * 注册全部内建 plugin runtime HTTP 路由。
+ */
+export function registerBuiltinPluginHttpRoutes(params: {
+  app: Hono;
+  getContext: () => AgentContext;
+}): void {
+  for (const plugin of PLUGINS) {
+    plugin.http?.runtime?.register({
+      app: params.app,
+      getContext: params.getContext,
+      pluginName: plugin.name,
+    });
+  }
+}