@downcity/plugins 1.0.4

package/src/workboard/runtime/Normalizer.ts

@@ -0,0 +1,213 @@
+/**
+ * Workboard 结构化归一化工具。
+ *
+ * 关键点（中文）
+ * - 这里负责把内部运行事实投影成“对外模糊公开态”。
+ * - 所有会泄漏上下文的字段都必须在这里截断或抽象。
+ */
+
+import type { ControlSessionSummary } from "@downcity/agent/internal/runtime/server/http/control/types/ControlViewData.js";
+import type { PluginStateSnapshot } from "@downcity/agent/internal/plugin/types/PluginState.js";
+import type { TaskListResponse } from "@/task/types/TaskCommand.js";
+import type {
+  WorkboardActivityItem,
+  WorkboardAgentSummary,
+  WorkboardSignalItem,
+  WorkboardSummary,
+} from "@/workboard/types/Workboard.js";
+import type { AgentContext } from "@downcity/agent/internal/types/runtime/agent/AgentContext.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;
+  plugins: PluginStateSnapshot[];
+  taskResult: TaskListResponse;
+}): WorkboardSignalItem[] {
+  const degradedCount = params.plugins.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/workboard/runtime/Store.ts

@@ -0,0 +1,110 @@
+/**
+ * Workboard 快照缓存。
+ *
+ * 关键点（中文）
+ * - 采用惰性启动 + 周期刷新，避免首次请求前就常驻占用资源。
+ * - route 与 action 共享同一份快照，确保 workboard 展示一致。
+ */
+
+import type { AgentContext } from "@downcity/agent/internal/types/runtime/agent/AgentContext.js";
+import type { WorkboardSnapshot } from "@/workboard/types/Workboard.js";
+import { collectWorkboardSnapshot } from "@/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/workboard/types/Workboard.ts

@@ -0,0 +1,158 @@
+/**
+ * Workboard 插件类型定义。
+ *
+ * 关键点（中文）
+ * - workboard 是对外展示面板，类型只保留公开安全的模糊状态。
+ * - 不暴露 sessionId、路径、模型、service 名称、task 明细等内部信息。
+ */
+
+/**
+ * Workboard 活动类型。
+ */
+export type WorkboardActivityKind = "focus" | "progress" | "idle";
+
+/**
+ * Workboard 活动状态。
+ */
+export type WorkboardActivityStatus = "active" | "steady" | "waiting" | "issue";
+
+/**
+ * Workboard 信号语气。
+ */
+export type WorkboardSignalTone = "neutral" | "accent" | "warning";
+
+/**
+ * 单个公开活动项。
+ */
+export interface WorkboardActivityItem {
+  /**
+   * 活动稳定标识。
+   */
+  id: string;
+  /**
+   * 活动类型。
+   */
+  kind: WorkboardActivityKind;
+  /**
+   * 对外可展示的模糊标题。
+   */
+  title: string;
+  /**
+   * 对外可展示的模糊摘要。
+   */
+  summary: string;
+  /**
+   * 当前状态。
+   */
+  status: WorkboardActivityStatus;
+  /**
+   * 最近更新时间（ISO8601）。
+   */
+  updatedAt: string;
+  /**
+   * 对外安全标签。
+   */
+  tags: string[];
+}
+
+/**
+ * 单个公开信号项。
+ */
+export interface WorkboardSignalItem {
+  /**
+   * 信号名称。
+   */
+  label: string;
+  /**
+   * 信号值。
+   */
+  value: string;
+  /**
+   * 信号语气。
+   */
+  tone: WorkboardSignalTone;
+}
+
+/**
+ * 顶部公开摘要。
+ */
+export interface WorkboardSummary {
+  /**
+   * 对外 headline。
+   */
+  headline: string;
+  /**
+   * 当前姿态描述。
+   */
+  posture: string;
+  /**
+   * 当前动量描述。
+   */
+  momentum: string;
+  /**
+   * 可见性说明。
+   */
+  visibilityNote: string;
+}
+
+/**
+ * agent 公开摘要。
+ */
+export interface WorkboardAgentSummary {
+  /**
+   * agent 展示名称。
+   */
+  name: string;
+  /**
+   * 当前 agent 是否运行中。
+   */
+  running: boolean;
+  /**
+   * 顶部状态文案。
+   */
+  statusText: string;
+  /**
+   * 最近采集时间（ISO8601）。
+   */
+  collectedAt: string;
+}
+
+/**
+ * Workboard 快照。
+ */
+export interface WorkboardSnapshot {
+  /**
+   * agent 公开摘要。
+   */
+  agent: WorkboardAgentSummary;
+  /**
+   * 顶部公开摘要。
+   */
+  summary: WorkboardSummary;
+  /**
+   * 当前活动列表。
+   */
+  current: WorkboardActivityItem[];
+  /**
+   * 最近活动列表。
+   */
+  recent: WorkboardActivityItem[];
+  /**
+   * 模糊信号列表。
+   */
+  signals: WorkboardSignalItem[];
+}
+
+/**
+ * Workboard 快照响应。
+ */
+export interface WorkboardSnapshotResponse {
+  /**
+   * 请求是否成功。
+   */
+  success: boolean;
+  /**
+   * 当前快照。
+   */
+  snapshot: WorkboardSnapshot;
+}

package/tsconfig.json

@@ -0,0 +1,26 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": ["ES2022"],
+    "outDir": "./bin",
+    "rootDir": "src",
+    "paths": {
+      "@/*": ["./src/*"],
+      "@downcity/agent": ["../agent/bin/index.d.ts"],
+      "@downcity/agent/internal/*": ["../agent/bin/*"]
+    },
+    "strict": true,
+    "noImplicitAny": false,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "bin"]
+}