@downcity/agent 1.1.7 → 1.1.10

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

@@ -0,0 +1,213 @@
+/**
+ * Workboard 结构化归一化工具。
+ *
+ * 关键点（中文）
+ * - 这里负责把内部运行事实投影成“对外模糊公开态”。
+ * - 所有会泄漏上下文的字段都必须在这里截断或抽象。
+ */
+
+import type { ControlSessionSummary } from "@/host/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 {
+  WorkboardActivityItem,
+  WorkboardAgentSummary,
+  WorkboardSignalItem,
+  WorkboardSummary,
+} from "@/plugin/builtins/workboard/types/Workboard.js";
+import type { AgentContext } from "@/agent/AgentContextTypes.js";
+
+function toIsoString(timestamp?: number): string {
+  if (!timestamp || !Number.isFinite(timestamp)) {
+    return new Date().toISOString();
+  }
+  return new Date(timestamp).toISOString();
+}
+
+function buildHeadline(params: {
+  currentCount: number;
+  recentCount: number;
+  degradedCount: number;
+}): string {
+  if (params.currentCount > 0 && params.degradedCount > 0) {
+    return "当前仍在展开，但节奏出现了一些波动";
+  }
+  if (params.currentCount > 1) {
+    return "当前呈现多线展开的状态";
+  }
+  if (params.currentCount === 1) {
+    return "当前呈现稳定展开的状态";
+  }
+  if (params.recentCount > 0) {
+    return "刚刚有过新的进展，现在进入短暂停留";
+  }
+  return "当前处于安静待命的状态";
+}
+
+function buildPosture(params: { currentCount: number; recentCount: number }): string {
+  if (params.currentCount > 1) return "多线展开";
+  if (params.currentCount === 1) return "单线聚焦";
+  if (params.recentCount > 0) return "短暂停留";
+  return "静候下一步";
+}
+
+function buildMomentum(params: { currentCount: number; recentCount: number }): string {
+  if (params.currentCount > 1) return "活跃展开";
+  if (params.currentCount === 1) return "平稳延续";
+  if (params.recentCount > 2) return "轻微起伏";
+  if (params.recentCount > 0) return "余温未散";
+  return "安静";
+}
+
+function buildRunningSummary(item: ControlSessionSummary): string {
+  const messageCount = typeof item.messageCount === "number" ? item.messageCount : 0;
+  if (messageCount >= 24) return "正在延展一段较长的工作脉络，并持续生成新的内容。";
+  if (messageCount >= 8) return "正在承接连续输入，逐步形成新的阶段结果。";
+  if (messageCount > 0) return "正在回应当前输入，并把工作继续向前展开。";
+  return "当前处于活跃展开之中。";
+}
+
+function buildRecentSummary(item: ControlSessionSummary, index: number): string {
+  const messageCount = typeof item.messageCount === "number" ? item.messageCount : 0;
+  if (index === 0 && messageCount > 0) return "刚刚完成一段新的展开，正在短暂停留。";
+  if (messageCount >= 12) return "近期完成了一次较长的内容延展。";
+  if (messageCount > 0) return "近期完成了一次常规更新。";
+  return "近期出现了一次轻微变化。";
+}
+
+/**
+ * 构建 agent 顶部公开摘要。
+ */
+export function toWorkboardAgentSummary(params: {
+  context: AgentContext;
+  collectedAt: string;
+  currentCount: number;
+  recentCount: number;
+  degradedCount: number;
+}): WorkboardAgentSummary {
+  const statusText = buildHeadline({
+    currentCount: params.currentCount,
+    recentCount: params.recentCount,
+    degradedCount: params.degradedCount,
+  });
+
+  return {
+    name: String(params.context.config.name || "").trim() || "agent",
+    running: true,
+    statusText,
+    collectedAt: params.collectedAt,
+  };
+}
+
+/**
+ * 将运行中的 session 映射为对外安全活动项。
+ */
+export function toRunningActivity(params: {
+  item: ControlSessionSummary;
+  index: number;
+}): WorkboardActivityItem {
+  const title = params.index === 0 ? "当前主线" : `当前并行线 ${params.index + 1}`;
+
+  return {
+    id: `current:${params.index + 1}`,
+    kind: "focus",
+    title,
+    summary: buildRunningSummary(params.item),
+    status: "active",
+    updatedAt: toIsoString(params.item.updatedAt),
+    tags: ["public", "active"],
+  };
+}
+
+/**
+ * 将近期 session 映射为对外安全活动项。
+ */
+export function toRecentActivity(params: {
+  item: ControlSessionSummary;
+  index: number;
+}): WorkboardActivityItem {
+  const title = params.index === 0 ? "最近一次更新" : `近期片段 ${params.index + 1}`;
+
+  return {
+    id: `recent:${params.index + 1}`,
+    kind: "progress",
+    title,
+    summary: buildRecentSummary(params.item, params.index),
+    status: params.index === 0 ? "steady" : "waiting",
+    updatedAt: toIsoString(params.item.updatedAt),
+    tags: ["public", "recent"],
+  };
+}
+
+/**
+ * 构建空闲占位项。
+ */
+export function buildIdleActivity(params: {
+  updatedAt: string;
+  recentCount: number;
+}): WorkboardActivityItem {
+  return {
+    id: "idle:standby",
+    kind: "idle",
+    title: "当前处于安静待命",
+    summary: params.recentCount > 0
+      ? "刚刚有过新的更新，现在等待下一次输入。"
+      : "当前没有明显变化，等待新的触发。",
+    status: "waiting",
+    updatedAt: params.updatedAt,
+    tags: ["public", "idle"],
+  };
+}
+
+/**
+ * 构建公开摘要。
+ */
+export function toWorkboardSummary(params: {
+  currentCount: number;
+  recentCount: number;
+  degradedCount: number;
+}): WorkboardSummary {
+  return {
+    headline: buildHeadline(params),
+    posture: buildPosture(params),
+    momentum: buildMomentum(params),
+    visibilityNote: "这里展示的是面向外部的概览状态，不包含内部上下文细节。",
+  };
+}
+
+/**
+ * 构建对外模糊信号。
+ */
+export function toWorkboardSignals(params: {
+  currentCount: number;
+  recentCount: number;
+  services: ServiceStateSnapshot[];
+  taskResult: TaskListResponse;
+}): WorkboardSignalItem[] {
+  const degradedCount = params.services.filter((item) => item.state !== "running").length;
+  const taskCount = Array.isArray(params.taskResult.tasks) ? params.taskResult.tasks.length : 0;
+
+  return [
+    {
+      label: "状态节奏",
+      value: params.currentCount > 1
+        ? "多线展开"
+        : params.currentCount === 1
+          ? "稳定展开"
+          : params.recentCount > 0
+            ? "轻微流动"
+            : "安静待命",
+      tone: params.currentCount > 0 ? "accent" : "neutral",
+    },
+    {
+      label: "现场感受",
+      value: degradedCount > 0 ? "有些波动" : "整体平稳",
+      tone: degradedCount > 0 ? "warning" : "neutral",
+    },
+    {
+      label: "活跃温度",
+      value: taskCount > 0 || params.recentCount > 0 ? "仍有余温" : "较为安静",
+      tone: params.recentCount > 0 ? "accent" : "neutral",
+    },
+  ];
+}

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

@@ -0,0 +1,110 @@
+/**
+ * Workboard 快照缓存。
+ *
+ * 关键点（中文）
+ * - 采用惰性启动 + 周期刷新，避免首次请求前就常驻占用资源。
+ * - route 与 action 共享同一份快照，确保 workboard 展示一致。
+ */
+
+import type { AgentContext } from "@/agent/AgentContextTypes.js";
+import type { WorkboardSnapshot } from "@/plugin/builtins/workboard/types/Workboard.js";
+import { collectWorkboardSnapshot } from "@/plugin/builtins/workboard/runtime/Collector.js";
+
+type AgentContextResolver = () => AgentContext;
+
+const DEFAULT_WORKBOARD_INTERVAL_MS = 5_000;
+
+/**
+ * Workboard 快照存储器。
+ */
+class WorkboardSnapshotStore {
+  private contextResolver: AgentContextResolver;
+
+  private readonly intervalMs: number;
+
+  private latestSnapshot: WorkboardSnapshot | null = null;
+
+  private refreshTimer: NodeJS.Timeout | null = null;
+
+  private inflight: Promise<WorkboardSnapshot> | null = null;
+
+  constructor(params: {
+    contextResolver: AgentContextResolver;
+    intervalMs?: number;
+  }) {
+    this.contextResolver = params.contextResolver;
+    this.intervalMs = params.intervalMs || DEFAULT_WORKBOARD_INTERVAL_MS;
+  }
+
+  /**
+   * 更新上下文 resolver。
+   */
+  setContextResolver(resolver: AgentContextResolver): void {
+    this.contextResolver = resolver;
+  }
+
+  /**
+   * 读取当前快照。
+   */
+  async readSnapshot(): Promise<WorkboardSnapshot> {
+    this.ensureStarted();
+    if (this.latestSnapshot) {
+      return this.latestSnapshot;
+    }
+    return this.refresh();
+  }
+
+  /**
+   * 立即刷新一次快照。
+   */
+  async refresh(): Promise<WorkboardSnapshot> {
+    if (this.inflight) {
+      return this.inflight;
+    }
+
+    this.inflight = collectWorkboardSnapshot(this.contextResolver())
+      .then((snapshot) => {
+        this.latestSnapshot = snapshot;
+        return snapshot;
+      })
+      .finally(() => {
+        this.inflight = null;
+      });
+
+    return this.inflight;
+  }
+
+  /**
+   * 惰性启动后台刷新。
+   */
+  private ensureStarted(): void {
+    if (this.refreshTimer) {
+      return;
+    }
+
+    void this.refresh();
+    this.refreshTimer = setInterval(() => {
+      void this.refresh();
+    }, this.intervalMs);
+    this.refreshTimer.unref?.();
+  }
+}
+
+let sharedStore: WorkboardSnapshotStore | null = null;
+
+/**
+ * 读取共享 workboard 快照缓存。
+ */
+export function getWorkboardSnapshotStore(params: {
+  contextResolver: AgentContextResolver;
+}): WorkboardSnapshotStore {
+  if (!sharedStore) {
+    sharedStore = new WorkboardSnapshotStore({
+      contextResolver: params.contextResolver,
+    });
+    return sharedStore;
+  }
+
+  sharedStore.setContextResolver(params.contextResolver);
+  return sharedStore;
+}

package/src/plugin/core/Activation.ts

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

package/src/plugin/core/Catalog.ts

@@ -0,0 +1,118 @@
+/**
+ * Plugin Catalog。
+ *
+ * 关键点（中文）
+ * - 这里承载 console 侧的静态 plugin 元数据视图。
+ * - 目标是把“控制面可见的 plugin 定义”从 agent 执行态里拆出来复用。
+ * - 当前先服务 Console 与 `city plugin` CLI 的静态回退场景。
+ */
+
+import { PLUGINS } from "@/plugin/core/Plugins.js";
+import { isPluginEnabled } from "@/plugin/core/Activation.js";
+import type {
+  Plugin,
+  PluginAvailability,
+  PluginView,
+} from "@/plugin/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."],
+  };
+}