@downcity/agent 1.1.8 → 1.1.10

package/src/host/http/control/ExecuteInput.ts

@@ -0,0 +1,236 @@
+/**
+ * Control execute 输入拼装 helper。
+ *
+ * 关键点（中文）
+ * - 负责把 API 传入的附件规范化并落盘。
+ * - 最终统一转成 `<file>` 标签注入到 user message。
+ */
+
+import fs from "fs-extra";
+import path from "node:path";
+import { getCacheDirPath } from "@/config/Paths.js";
+import { renderChatMessageFileTag } from "@/service/builtins/chat/runtime/ChatMessageMarkup.js";
+import type {
+  ControlSessionExecuteAttachmentInput,
+  ControlSessionExecuteAttachmentType,
+} from "@/host/http/control/types/ControlSessionExecute.js";
+
+const EXECUTE_ATTACHMENT_MAX_COUNT = 8;
+const EXECUTE_ATTACHMENT_MAX_BYTES = 2 * 1024 * 1024;
+const EXECUTE_ATTACHMENT_CONTENT_MAX_CHARS = 1_500_000;
+const EXECUTE_ATTACHMENT_FALLBACK_TEXT = "请查看以上附件并按用户要求处理。";
+
+function normalizeExecuteAttachmentType(
+  value: unknown,
+): ControlSessionExecuteAttachmentType {
+  const raw = String(value || "")
+    .trim()
+    .toLowerCase();
+  if (
+    raw === "photo" ||
+    raw === "voice" ||
+    raw === "audio" ||
+    raw === "video"
+  ) {
+    return raw;
+  }
+  return "document";
+}
+
+function normalizeAttachmentCaption(value: unknown): string | undefined {
+  const text = String(value || "")
+    .replace(/\r?\n+/g, " ")
+    .replace(/\s+/g, " ")
+    .replace(/\|/g, "/")
+    .trim();
+  if (!text) return undefined;
+  return text.slice(0, 180);
+}
+
+function toProjectRelativePath(projectRoot: string, absPath: string): string | null {
+  const relative = path.relative(projectRoot, absPath);
+  if (!relative) return null;
+  if (relative.startsWith("..")) return null;
+  if (path.isAbsolute(relative)) return null;
+  return relative.split(path.sep).join("/");
+}
+
+function normalizeAttachmentFileName(params: {
+  fileName?: string;
+  fallbackExt: string;
+}): string {
+  const raw = String(params.fileName || "").trim();
+  const base = (raw || "attachment")
+    .replace(/[\\/:*?"<>|]/g, "-")
+    .replace(/\s+/g, "-")
+    .replace(/-+/g, "-")
+    .replace(/^\.+/, "")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 72);
+  const safeBase = base || "attachment";
+  const fallbackExt = params.fallbackExt.startsWith(".")
+    ? params.fallbackExt
+    : `.${params.fallbackExt}`;
+  const hasExt = /\.[A-Za-z0-9]+$/.test(safeBase);
+  return hasExt ? safeBase : `${safeBase}${fallbackExt}`;
+}
+
+function inferAttachmentExt(params: {
+  type: ControlSessionExecuteAttachmentType;
+  fileName?: string;
+  contentType?: string;
+}): string {
+  const fromFileName = path.extname(String(params.fileName || "").trim())
+    .toLowerCase()
+    .trim();
+  if (fromFileName) return fromFileName;
+  const contentType = String(params.contentType || "").toLowerCase();
+  if (contentType.includes("markdown")) return ".md";
+  if (contentType.includes("json")) return ".json";
+  if (contentType.includes("html")) return ".html";
+  if (contentType.includes("plain")) return ".txt";
+  if (params.type === "photo") return ".jpg";
+  if (params.type === "voice" || params.type === "audio") return ".mp3";
+  if (params.type === "video") return ".mp4";
+  return ".md";
+}
+
+async function resolveAttachmentPathFromInput(params: {
+  projectRoot: string;
+  attachment: ControlSessionExecuteAttachmentInput;
+}): Promise<string | null> {
+  const rawPath = String(params.attachment.path || "").trim();
+  if (!rawPath) return null;
+  const abs = path.isAbsolute(rawPath)
+    ? path.normalize(rawPath)
+    : path.resolve(params.projectRoot, rawPath);
+  const relative = toProjectRelativePath(params.projectRoot, abs);
+  if (!relative) return null;
+  const stat = await fs
+    .stat(abs)
+    .then((value) => value)
+    .catch(() => null);
+  if (!stat?.isFile()) return null;
+  return relative;
+}
+
+function resolveAttachmentBytes(
+  attachment: ControlSessionExecuteAttachmentInput,
+): Buffer | null {
+  const textContent =
+    typeof attachment.content === "string" ? attachment.content : "";
+  if (textContent) {
+    const clipped = textContent.slice(0, EXECUTE_ATTACHMENT_CONTENT_MAX_CHARS);
+    return Buffer.from(clipped, "utf8");
+  }
+
+  const base64 = String(attachment.contentBase64 || "").trim();
+  if (!base64) return null;
+  try {
+    return Buffer.from(base64, "base64");
+  } catch {
+    return null;
+  }
+}
+
+async function materializeAttachmentContent(params: {
+  projectRoot: string;
+  sessionId: string;
+  attachment: ControlSessionExecuteAttachmentInput;
+  index: number;
+}): Promise<string | null> {
+  const bytes = resolveAttachmentBytes(params.attachment);
+  if (!bytes || bytes.length <= 0) return null;
+  if (bytes.length > EXECUTE_ATTACHMENT_MAX_BYTES) {
+    throw new Error(
+      `Attachment too large (>${EXECUTE_ATTACHMENT_MAX_BYTES} bytes)`,
+    );
+  }
+
+  const type = normalizeExecuteAttachmentType(params.attachment.type);
+  const ext = inferAttachmentExt({
+    type,
+    fileName: params.attachment.fileName,
+    contentType: params.attachment.contentType,
+  });
+  const safeName = normalizeAttachmentFileName({
+    fileName: params.attachment.fileName,
+    fallbackExt: ext,
+  });
+  const safeContext = String(params.sessionId || "session")
+    .replace(/[^A-Za-z0-9_-]+/g, "-")
+    .replace(/-+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 32);
+  const prefix = safeContext || "context";
+  const fileName = `${Date.now()}-${prefix}-${String(params.index + 1).padStart(2, "0")}-${safeName}`;
+  const cacheDir = path.join(getCacheDirPath(params.projectRoot), "chrome-extension");
+  await fs.ensureDir(cacheDir);
+  const absPath = path.join(cacheDir, fileName);
+  await fs.writeFile(absPath, bytes);
+  return toProjectRelativePath(params.projectRoot, absPath);
+}
+
+function toAttachmentLine(params: {
+  type: ControlSessionExecuteAttachmentType;
+  relativePath: string;
+  caption?: string;
+}): string {
+  return renderChatMessageFileTag({
+    type: params.type,
+    path: params.relativePath,
+    ...(params.caption ? { caption: params.caption } : {}),
+  });
+}
+
+/**
+ * 构造 execute 入站文本。
+ */
+export async function buildExecuteInputText(params: {
+  projectRoot: string;
+  sessionId: string;
+  instructions: string;
+  attachments?: ControlSessionExecuteAttachmentInput[];
+}): Promise<string> {
+  const instructions = String(params.instructions || "").trim();
+  const inputAttachments = Array.isArray(params.attachments)
+    ? params.attachments.slice(0, EXECUTE_ATTACHMENT_MAX_COUNT)
+    : [];
+  if (inputAttachments.length === 0) return instructions;
+
+  const lines: string[] = [];
+  for (let index = 0; index < inputAttachments.length; index += 1) {
+    const attachment = inputAttachments[index];
+    if (!attachment || typeof attachment !== "object") continue;
+    const type = normalizeExecuteAttachmentType(attachment.type);
+    const caption = normalizeAttachmentCaption(attachment.caption);
+
+    const reusePath = await resolveAttachmentPathFromInput({
+      projectRoot: params.projectRoot,
+      attachment,
+    });
+    const relativePath =
+      reusePath ||
+      (await materializeAttachmentContent({
+        projectRoot: params.projectRoot,
+        sessionId: params.sessionId,
+        attachment,
+        index,
+      }));
+    if (!relativePath) continue;
+
+    lines.push(
+      toAttachmentLine({
+        type,
+        relativePath,
+        ...(caption ? { caption } : {}),
+      }),
+    );
+  }
+
+  if (lines.length === 0) return instructions;
+  return [lines.join("\n"), instructions || EXECUTE_ATTACHMENT_FALLBACK_TEXT]
+    .filter(Boolean)
+    .join("\n\n")
+    .trim();
+}

package/src/host/http/control/MessageTimeline.ts

@@ -0,0 +1,269 @@
+/**
+ * Control 消息时间线 helper。
+ *
+ * 关键点（中文）
+ * - 负责把上下文消息映射成 control UI 可视时间线。
+ * - 同时提供消息文件读取能力。
+ */
+
+import fs from "fs-extra";
+import {
+  getToolName,
+  isTextUIPart,
+  isToolUIPart,
+  type UIMessagePart,
+} from "ai";
+import type {
+  SessionMessageV1,
+  SessionMetadataV1,
+} from "@/session/types/SessionMessages.js";
+import { pickLastSuccessfulChatSendText } from "@/service/builtins/chat/runtime/UserVisibleText.js";
+import { extractToolCallsFromUiMessage } from "@/service/builtins/chat/runtime/UIMessageTransformer.js";
+import type { ControlTimelineEvent, ControlTimelineRole } from "@/host/http/control/types/ControlViewData.js";
+import { truncateText } from "./CommonHelpers.js";
+
+type AnyUiPart = UIMessagePart<Record<string, never>, Record<string, never>>;
+
+type ToolPartCompatShape = {
+  type?: unknown;
+  state?: unknown;
+  input?: unknown;
+  output?: unknown;
+  errorText?: unknown;
+  error?: unknown;
+  approval?: { reason?: unknown } | null;
+};
+
+function stringifyForDisplay(input: unknown, maxChars = 2400): string {
+  if (input === undefined) return "";
+  if (input === null) return "null";
+  if (typeof input === "string") {
+    const value = input.trim();
+    if (!value) return "";
+    try {
+      const parsed = JSON.parse(value);
+      return truncateText(JSON.stringify(parsed, null, 2), maxChars);
+    } catch {
+      return truncateText(value, maxChars);
+    }
+  }
+  if (typeof input === "number" || typeof input === "boolean") {
+    return truncateText(String(input), maxChars);
+  }
+  try {
+    return truncateText(JSON.stringify(input, null, 2), maxChars);
+  } catch {
+    return truncateText(String(input), maxChars);
+  }
+}
+
+function extractMessageText(parts: unknown): string {
+  if (!Array.isArray(parts)) return "";
+  const texts: string[] = [];
+  for (const part of parts) {
+    if (!part || typeof part !== "object") continue;
+    const p = part as { type?: unknown; text?: unknown };
+    if (p.type !== "text") continue;
+    if (typeof p.text !== "string") continue;
+    const value = p.text.trim();
+    if (!value) continue;
+    texts.push(value);
+  }
+  return texts.join("\n").trim();
+}
+
+function extractAssistantToolSummary(message: SessionMessageV1): string {
+  const toolCalls = extractToolCallsFromUiMessage(message);
+  if (!Array.isArray(toolCalls) || toolCalls.length === 0) return "";
+  const toolNames = Array.from(
+    new Set(toolCalls.map((item) => String(item.tool || "").trim()).filter(Boolean)),
+  );
+  if (toolNames.length === 0) return "";
+  return `[tool] ${toolNames.join(", ")}`;
+}
+
+function resolveToolName(part: ToolPartCompatShape, aiToolName?: string): string {
+  const fromAi = String(aiToolName || "").trim();
+  if (fromAi) return fromAi;
+
+  const rawType = typeof part.type === "string" ? part.type.trim() : "";
+  if (rawType.startsWith("tool-")) return rawType.slice("tool-".length);
+  return "unknown_tool";
+}
+
+function extractToolCallInput(part: ToolPartCompatShape): unknown {
+  return part.input ?? undefined;
+}
+
+function extractToolResultOutput(part: ToolPartCompatShape): unknown {
+  const state = typeof part.state === "string" ? part.state.trim() : "";
+  if (state === "output-available") return part.output;
+  if (state === "output-error") {
+    return { error: part.errorText ?? part.error ?? "tool_error" };
+  }
+  if (state === "output-denied") {
+    return {
+      error: "tool_denied",
+      reason: part.approval?.reason ?? "",
+    };
+  }
+  if (
+    state === "input-available" ||
+    state === "input-streaming" ||
+    state === "output-streaming"
+  ) {
+    return undefined;
+  }
+  return undefined;
+}
+
+function toUiMessageEvent(params: {
+  message: SessionMessageV1;
+  role: ControlTimelineRole;
+  text: string;
+  sequence: number;
+  toolName?: string;
+}): ControlTimelineEvent {
+  const { message, role, text, sequence, toolName } = params;
+  const metadata = (message.metadata || null) as SessionMetadataV1 | null;
+
+  return {
+    id: `${String(message.id || "")}:${sequence}`,
+    role,
+    ...(typeof metadata?.ts === "number" ? { ts: metadata.ts } : {}),
+    ...(typeof metadata?.kind === "string" ? { kind: metadata.kind } : {}),
+    ...(typeof metadata?.source === "string" ? { source: metadata.source } : {}),
+    text,
+    ...(toolName ? { toolName } : {}),
+  };
+}
+
+function resolveUiMessageText(message: SessionMessageV1): string {
+  const plainText = extractMessageText(message.parts);
+  if (plainText) return plainText;
+
+  if (message.role !== "assistant") return "";
+
+  const userVisible = pickLastSuccessfulChatSendText(message).trim();
+  if (userVisible) return userVisible;
+
+  return extractAssistantToolSummary(message);
+}
+
+/**
+ * 转成 control 时间线。
+ */
+export function toUiMessageTimeline(
+  message: SessionMessageV1,
+): ControlTimelineEvent[] {
+  if (message.role !== "assistant") {
+    return [
+      toUiMessageEvent({
+        message,
+        role: message.role,
+        text: resolveUiMessageText(message),
+        sequence: 0,
+      }),
+    ];
+  }
+
+  const parts = Array.isArray(message.parts)
+    ? (message.parts as AnyUiPart[])
+    : [];
+  const events: ControlTimelineEvent[] = [];
+  let sequence = 0;
+
+  for (const part of parts) {
+    if (!part || typeof part !== "object") continue;
+    const partObject = part as ToolPartCompatShape;
+
+    if (isTextUIPart(part)) {
+      const text = String(part.text || "").trim();
+      if (!text) continue;
+      events.push(
+        toUiMessageEvent({
+          message,
+          role: "assistant",
+          text,
+          sequence,
+        }),
+      );
+      sequence += 1;
+      continue;
+    }
+
+    if (isToolUIPart(part)) {
+      const toolName = resolveToolName(partObject, String(getToolName(part) || ""));
+      const inputText = stringifyForDisplay(extractToolCallInput(partObject));
+      events.push(
+        toUiMessageEvent({
+          message,
+          role: "tool-call",
+          text: inputText || "(empty)",
+          sequence,
+          toolName,
+        }),
+      );
+      sequence += 1;
+
+      const output = extractToolResultOutput(partObject);
+      if (output !== undefined) {
+        events.push(
+          toUiMessageEvent({
+            message,
+            role: "tool-result",
+            text: stringifyForDisplay(output) || "(empty)",
+            sequence,
+            toolName,
+          }),
+        );
+        sequence += 1;
+      }
+      continue;
+    }
+  }
+
+  // 关键点（中文）：assistant 若没有文本 part，也要保留一条可见事件，避免 control UI 空白。
+  if (events.length === 0) {
+    events.push(
+      toUiMessageEvent({
+        message,
+        role: "assistant",
+        text: resolveUiMessageText(message),
+        sequence: 0,
+      }),
+    );
+  }
+
+  return events;
+}
+
+/**
+ * 读取 session 消息文件。
+ */
+export async function loadSessionMessagesFromFile(
+  filePath: string,
+): Promise<SessionMessageV1[]> {
+  if (!(await fs.pathExists(filePath))) return [];
+  const raw = await fs.readFile(filePath, "utf-8");
+  const lines = raw.split("\n").filter(Boolean);
+  const out: SessionMessageV1[] = [];
+  for (const line of lines) {
+    try {
+      const item = JSON.parse(line) as SessionMessageV1;
+      if (!item || typeof item !== "object") continue;
+      if (item.role !== "user" && item.role !== "assistant") continue;
+      out.push(item);
+    } catch {
+      // 关键点（中文）：单行损坏不应影响整体可读性。
+    }
+  }
+  return out;
+}
+
+/**
+ * 读取适合摘要展示的消息预览文本。
+ */
+export function resolveUiMessagePreview(message: SessionMessageV1): string {
+  return resolveUiMessageText(message);
+}

package/src/host/http/control/ModelRoutes.ts

@@ -0,0 +1,101 @@
+/**
+ * Control 模型路由。
+ *
+ * 关键点（中文）
+ * - 仅承接当前 agent 视角下的模型展示与切换。
+ * - 控制面全局模型池管理仍由 `/api/ui/model*` 处理。
+ */
+
+import fs from "fs-extra";
+import { getDowncityJsonPath } from "@/config/Paths.js";
+import type { ControlRouteRegistrationParams } from "@/host/http/control/types/ControlRoutes.js";
+import { buildControlRouteAliases } from "@/host/http/control/CommonHelpers.js";
+
+/**
+ * 注册模型相关路由。
+ */
+export function registerControlModelRoutes(
+  params: ControlRouteRegistrationParams,
+): void {
+  const { app } = params;
+
+  for (const routePath of buildControlRouteAliases("/model")) {
+    app.get(routePath, async (c) => {
+      try {
+        const agentState = params.getAgentRuntime();
+        const agentPrimaryModelId = String(agentState.config.execution?.type === "api" ? agentState.config.execution.modelId || "" : "").trim();
+        const models = agentState.platform.listModels();
+        const providers = await agentState.platform.listProviders();
+        const providerMap = new Map(providers.map((x) => [x.id, x] as const));
+        const activeModel = agentPrimaryModelId
+          ? models.find((x) => x.id === agentPrimaryModelId)
+          : undefined;
+        const providerKey = String(activeModel?.providerId || "").trim();
+        const provider = providerKey ? providerMap.get(providerKey) : undefined;
+        const availableModels = models.map((model) => {
+          const providerConfig = providerMap.get(model.providerId);
+          return {
+            id: model.id,
+            name: model.name,
+            providerKey: model.providerId,
+            providerType: String(providerConfig?.type || "").trim(),
+          };
+        });
+        return c.json({
+          success: true,
+          model: {
+            primaryModelId: agentPrimaryModelId,
+            primaryModelName: String(activeModel?.name || "").trim(),
+            providerKey,
+            providerType: String(provider?.type || "").trim(),
+            baseUrl: String(provider?.baseUrl || "").trim(),
+            agentPrimaryModelId,
+            availableModels,
+          },
+        });
+      } catch (error) {
+        return c.json({ success: false, error: String(error) }, 500);
+      }
+    });
+  }
+
+  for (const routePath of buildControlRouteAliases("/model/switch")) {
+    app.post(routePath, async (c) => {
+      try {
+        const agentState = params.getAgentRuntime();
+        const body = (await c.req.json().catch(() => ({}))) as {
+          primaryModelId?: string;
+        };
+        const nextPrimaryModelId = String(body.primaryModelId || "").trim();
+        if (!nextPrimaryModelId) {
+          return c.json({ success: false, error: "Missing primaryModelId" }, 400);
+        }
+        const targetModel = agentState.platform.getModel(nextPrimaryModelId);
+        if (!targetModel) {
+          return c.json(
+            { success: false, error: `Model not found: ${nextPrimaryModelId}` },
+            400,
+          );
+        }
+
+        const shipJsonPath = getDowncityJsonPath(agentState.rootPath);
+        const agentShip = (await fs.readJson(shipJsonPath)) as {
+          execution?: { type?: string; modelId?: string };
+        };
+        agentShip.execution = { type: "api", modelId: nextPrimaryModelId };
+        await fs.writeJson(shipJsonPath, agentShip, { spaces: 2 });
+
+        agentState.config.execution = { type: "api", modelId: nextPrimaryModelId };
+
+        return c.json({
+          success: true,
+          primaryModelId: nextPrimaryModelId,
+          restartRequired: true,
+          message: "Agent primary model updated. Restart agent to fully apply the new model instance.",
+        });
+      } catch (error) {
+        return c.json({ success: false, error: String(error) }, 500);
+      }
+    });
+  }
+}

package/src/host/http/control/OverviewRoutes.ts

@@ -0,0 +1,106 @@
+/**
+ * Control 概览路由。
+ *
+ * 关键点（中文）
+ * - 聚合 overview 与 services 两块轻量只读接口。
+ * - 只负责路由层拼装，不承载复杂业务状态机。
+ */
+
+import fs from "fs-extra";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+import { listServiceStates } from "@/service/core/Manager.js";
+import { listTaskDefinitions } from "@/service/builtins/task/Action.js";
+import { buildControlRouteAliases, toLimit } from "./CommonHelpers.js";
+import { listControlSessionSummaries, readRecentLogs } from "./Helpers.js";
+import type { ControlRouteRegistrationParams } from "@/host/http/control/types/ControlRoutes.js";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+/**
+ * 当前 DC 版本号（用于 Overview 显示）。
+ */
+const DC_VERSION = (() => {
+  try {
+    const pkg = fs.readJsonSync(join(__dirname, "../../../package.json")) as {
+      version?: string;
+    };
+    const version = String(pkg?.version || "").trim();
+    return version || "unknown";
+  } catch {
+    return "unknown";
+  }
+})();
+
+/**
+ * 注册概览与服务路由。
+ */
+export function registerControlOverviewRoutes(
+  params: ControlRouteRegistrationParams,
+): void {
+  const { app } = params;
+
+  for (const routePath of buildControlRouteAliases("/overview")) {
+    app.get(routePath, async (c) => {
+      try {
+        const runtime = params.getAgentRuntime();
+        const sessionLimit = toLimit(
+          c.req.query("sessionLimit") || c.req.query("contextLimit"),
+          20,
+        );
+        const sessions = await listControlSessionSummaries({
+          projectRoot: runtime.rootPath,
+          executionContext: params.getAgentContext(),
+          limit: sessionLimit,
+        });
+        const services = listServiceStates();
+        const taskResult = await listTaskDefinitions({
+          projectRoot: runtime.rootPath,
+        });
+        const tasks = Array.isArray(taskResult.tasks) ? taskResult.tasks : [];
+        const logs = await readRecentLogs({
+          projectRoot: runtime.rootPath,
+          limit: 50,
+        });
+
+        const statusCount = {
+          enabled: tasks.filter((x) => x.status === "enabled").length,
+          paused: tasks.filter((x) => x.status === "paused").length,
+          disabled: tasks.filter((x) => x.status === "disabled").length,
+        };
+
+        return c.json({
+          success: true,
+          cityVersion: DC_VERSION,
+          now: new Date().toISOString(),
+          agent: {
+            name: runtime.config.name,
+            status: "running",
+          },
+          sessions: {
+            total: sessions.length,
+            items: sessions,
+          },
+          services,
+          tasks: {
+            total: tasks.length,
+            statusCount,
+          },
+          logs,
+        });
+      } catch (error) {
+        return c.json({ success: false, error: String(error) }, 500);
+      }
+    });
+  }
+
+  for (const routePath of buildControlRouteAliases("/services")) {
+    app.get(routePath, (c) => {
+      return c.json({
+        success: true,
+        services: listServiceStates(),
+      });
+    });
+  }
+}