@downcity/agent 1.1.408 → 1.1.437

package/src/session/messages/SessionTurnFileDiffBuilder.ts

@@ -0,0 +1,229 @@
+/**
+ * Session Turn 结构化文件修改的 Diff 构建器。
+ *
+ * 关键点（中文）
+ * - 从当前 Turn 的通用 Tool effects 中只选择 Workspace 文件修改事实。
+ * - 不读取 Turn 结束时的实时工作树，因此 Shell 和外部进程不会被反向归属。
+ * - 同一文件的修改状态无法连续证明时直接忽略，避免把外部插入的内容伪装成本轮修改。
+ */
+
+import path from "node:path";
+import {
+  FILE_HEADERS_ONLY,
+  formatPatch,
+  structuredPatch,
+} from "diff";
+import type { RuntimeToolEffect } from "@downcity/type";
+import {
+  WORKSPACE_FILE_MUTATION_EFFECT_TYPE,
+  type WorkspaceFileMutation,
+  type WorkspaceFileMutationState,
+} from "@downcity/type";
+import type {
+  SessionTurnFileDiff,
+  SessionTurnFileDiffData,
+  SessionTurnFileDiffStatus,
+  SessionTurnFileDiffSummary,
+} from "@downcity/type";
+
+interface CollectedFileMutation {
+  /** 相对于当前 Workspace 根目录的规范化路径。 */
+  file: string;
+  /** 当前 Turn 第一次结构化修改前的文件状态。 */
+  before: WorkspaceFileMutationState;
+  /** 当前 Turn 最后一次连续结构化修改后的文件状态。 */
+  after: WorkspaceFileMutationState;
+  /** 前后修改链是否被其他写入打断。 */
+  conflicted: boolean;
+}
+
+/** 把当前 Turn effects 中的结构化文件修改收敛为可持久化 Diff。 */
+export function build_session_turn_file_diff(
+  workspace_path: string,
+  effects: readonly RuntimeToolEffect[],
+): SessionTurnFileDiffData | undefined {
+  const files = collect_session_turn_file_diffs(workspace_path, effects);
+  if (files.length === 0) return undefined;
+  return {
+    files,
+    additions: files.reduce((total, file) => total + file.additions, 0),
+    deletions: files.reduce((total, file) => total + file.deletions, 0),
+  };
+}
+
+/** 从当前 Turn effects 收敛只含统计的实时摘要，供 Thinking 状态行轻量展示。 */
+export function build_session_turn_file_diff_summary(
+  workspace_path: string,
+  effects: readonly RuntimeToolEffect[],
+): SessionTurnFileDiffSummary {
+  const files = collect_session_turn_file_diffs(workspace_path, effects);
+  return {
+    files_count: files.length,
+    additions: files.reduce((total, file) => total + file.additions, 0),
+    deletions: files.reduce((total, file) => total + file.deletions, 0),
+  };
+}
+
+/** 把 effects 收敛为稳定排序的文件 Diff 列表；空列表表示当前没有结构化修改。 */
+function collect_session_turn_file_diffs(
+  workspace_path: string,
+  effects: readonly RuntimeToolEffect[],
+): SessionTurnFileDiff[] {
+  const mutations = effects.flatMap((effect) => {
+    const mutation = read_workspace_file_mutation_effect(effect);
+    return mutation ? [mutation] : [];
+  });
+  const files_by_path = collect_file_mutations(workspace_path, mutations);
+  return [...files_by_path.values()]
+    .filter((entry) => !entry.conflicted && !same_file_state(entry.before, entry.after))
+    .map(create_file_diff)
+    .sort((left, right) => left.file.localeCompare(right.file));
+}
+
+/** 从通用 Tool effect 中读取经过最小运行时校验的 Workspace 文件修改。 */
+function read_workspace_file_mutation_effect(
+  input: unknown,
+): WorkspaceFileMutation | undefined {
+  if (!input || typeof input !== "object" || Array.isArray(input)) return undefined;
+  const effect = input as Record<string, unknown>;
+  if (effect.type !== WORKSPACE_FILE_MUTATION_EFFECT_TYPE) return undefined;
+  if (!effect.data || typeof effect.data !== "object" || Array.isArray(effect.data)) {
+    return undefined;
+  }
+  const mutation = effect.data as Record<string, unknown>;
+  if (
+    typeof mutation.file_path !== "string" ||
+    !is_file_state(mutation.before) ||
+    !is_file_state(mutation.after)
+  ) return undefined;
+  return {
+    file_path: mutation.file_path,
+    before: mutation.before,
+    after: mutation.after,
+  };
+}
+
+/** 按文件聚合连续的结构化修改；无法证明连续时标记冲突。 */
+function collect_file_mutations(
+  workspace_path: string,
+  mutations: readonly WorkspaceFileMutation[],
+): Map<string, CollectedFileMutation> {
+  const workspace_root = path.resolve(workspace_path);
+  const files_by_path = new Map<string, CollectedFileMutation>();
+  for (const mutation of mutations) {
+    const file = resolve_workspace_file(workspace_root, mutation.file_path);
+    if (!file) continue;
+    const existing = files_by_path.get(file);
+    if (!existing) {
+      files_by_path.set(file, {
+        file,
+        before: mutation.before,
+        after: mutation.after,
+        conflicted: false,
+      });
+      continue;
+    }
+    if (!same_file_state(existing.after, mutation.before)) existing.conflicted = true;
+    existing.after = mutation.after;
+  }
+  return files_by_path;
+}
+
+/** 把绝对修改路径收窄为当前 Workspace 内的正斜杠相对路径。 */
+function resolve_workspace_file(workspace_root: string, file_path: string): string | undefined {
+  if (typeof file_path !== "string" || !file_path.trim()) return undefined;
+  if (!path.isAbsolute(file_path)) return undefined;
+  const resolved_path = path.resolve(file_path);
+  const relative_path = path.relative(workspace_root, resolved_path);
+  if (
+    !relative_path ||
+    relative_path === ".." ||
+    relative_path.startsWith(`..${path.sep}`) ||
+    path.isAbsolute(relative_path)
+  ) {
+    return undefined;
+  }
+  return relative_path.replaceAll(path.sep, "/");
+}
+
+/** 校验 Workspace 修改状态的最小运行时形状。 */
+function is_file_state(input: unknown): input is WorkspaceFileMutationState {
+  if (!input || typeof input !== "object" || Array.isArray(input)) return false;
+  const state = input as Record<string, unknown>;
+  return typeof state.exists === "boolean" &&
+    (state.sha256 === undefined || typeof state.sha256 === "string") &&
+    (state.content === undefined || typeof state.content === "string");
+}
+
+/** 使用内容 hash 优先判断两个相邻修改状态是否连续。 */
+function same_file_state(
+  left: WorkspaceFileMutationState,
+  right: WorkspaceFileMutationState,
+): boolean {
+  if (left.exists !== right.exists) return false;
+  if (!left.exists) return true;
+  if (left.sha256 && right.sha256) return left.sha256 === right.sha256;
+  if (left.content !== undefined && right.content !== undefined) {
+    return left.content === right.content;
+  }
+  return false;
+}
+
+/** 为单个连续文件修改生成统计与 unified patch。 */
+function create_file_diff(entry: CollectedFileMutation): SessionTurnFileDiff {
+  const status: SessionTurnFileDiffStatus = !entry.before.exists
+    ? "added"
+    : !entry.after.exists
+      ? "deleted"
+      : "modified";
+  const before_content = entry.before.exists ? entry.before.content : "";
+  const after_content = entry.after.exists ? entry.after.content : "";
+  const text_diff = before_content !== undefined && after_content !== undefined
+    ? create_text_patch(entry.file, status, before_content, after_content)
+    : undefined;
+  return {
+    file: entry.file,
+    status,
+    additions: text_diff?.additions ?? 0,
+    deletions: text_diff?.deletions ?? 0,
+    patch: text_diff?.patch ?? create_binary_patch(entry.file),
+  };
+}
+
+/** 生成 Git 风格文件头与标准 unified hunks。 */
+function create_text_patch(
+  file: string,
+  status: SessionTurnFileDiffStatus,
+  before: string,
+  after: string,
+): { patch: string; additions: number; deletions: number } {
+  const old_file = status === "added" ? "/dev/null" : `a/${file}`;
+  const new_file = status === "deleted" ? "/dev/null" : `b/${file}`;
+  const structured = structuredPatch(old_file, new_file, before, after, "", "", { context: 3 });
+  let additions = 0;
+  let deletions = 0;
+  for (const hunk of structured.hunks) {
+    for (const line of hunk.lines) {
+      if (line.startsWith("+")) additions += 1;
+      else if (line.startsWith("-")) deletions += 1;
+    }
+  }
+  const header = [
+    `diff --git a/${file} b/${file}`,
+    ...(status === "added" ? ["new file mode 100644"] : []),
+    ...(status === "deleted" ? ["deleted file mode 100644"] : []),
+  ];
+  return {
+    additions,
+    deletions,
+    patch: `${header.join("\n")}\n${formatPatch(structured, FILE_HEADERS_ONLY).trimEnd()}`,
+  };
+}
+
+/** 无法安全保留文本内容时生成不伪造行级统计的变化说明。 */
+function create_binary_patch(file: string): string {
+  return [
+    `diff --git a/${file} b/${file}`,
+    `Binary files a/${file} and b/${file} differ`,
+  ].join("\n");
+}

package/src/session/messages/SessionTurnFileDiffData.ts

@@ -0,0 +1,72 @@
+/**
+ * Session Turn 文件改动 data part 的协议辅助函数。
+ *
+ * 这里集中维护稳定 data_type 与运行时校验，避免 Desktop、远程客户端和插件各自解释
+ * 任意 JSON 结构。
+ */
+
+import type { SessionAgentDataPart } from "@downcity/type";
+import type {
+  SessionTurnFileDiff,
+  SessionTurnFileDiffData,
+  SessionTurnFileDiffStatus,
+} from "@downcity/type";
+
+/** 当前 Turn 文件改动使用的稳定 Assistant data part 类型。 */
+export const SESSION_TURN_FILE_DIFF_DATA_TYPE = "data-session-turn-file-diff";
+
+/** 从 Assistant data part 中读取经过校验的 Turn 文件改动。 */
+export function read_session_turn_file_diff_data(
+  part: SessionAgentDataPart,
+): SessionTurnFileDiffData | undefined {
+  if (part.data_type !== SESSION_TURN_FILE_DIFF_DATA_TYPE) return undefined;
+  if (!is_record(part.data) || !Array.isArray(part.data.files)) return undefined;
+  const files = part.data.files.flatMap((candidate) => {
+    const file_diff = read_file_diff(candidate);
+    return file_diff ? [file_diff] : [];
+  });
+  if (files.length !== part.data.files.length) return undefined;
+  const additions = read_count(part.data.additions);
+  const deletions = read_count(part.data.deletions);
+  if (additions === undefined || deletions === undefined) return undefined;
+  return { files, additions, deletions };
+}
+
+/** 判断 data part 是否为有效的 Turn 文件改动。 */
+export function is_session_turn_file_diff_data_part(
+  part: SessionAgentDataPart,
+): boolean {
+  return read_session_turn_file_diff_data(part) !== undefined;
+}
+
+/** 读取单个文件差异并收窄未知 JSON。 */
+function read_file_diff(input: unknown): SessionTurnFileDiff | undefined {
+  if (!is_record(input)) return undefined;
+  const file = typeof input.file === "string" ? input.file : "";
+  const status = input.status;
+  const additions = read_count(input.additions);
+  const deletions = read_count(input.deletions);
+  if (
+    !file ||
+    !is_file_diff_status(status) ||
+    additions === undefined ||
+    deletions === undefined ||
+    typeof input.patch !== "string"
+  ) return undefined;
+  return { file, status, additions, deletions, patch: input.patch };
+}
+
+/** 文件状态只接受 canonical 三种值。 */
+function is_file_diff_status(input: unknown): input is SessionTurnFileDiffStatus {
+  return input === "added" || input === "deleted" || input === "modified";
+}
+
+/** 行数必须是非负整数。 */
+function read_count(input: unknown): number | undefined {
+  return Number.isInteger(input) && Number(input) >= 0 ? Number(input) : undefined;
+}
+
+/** 将未知值收窄为普通对象。 */
+function is_record(input: unknown): input is Record<string, unknown> {
+  return Boolean(input) && typeof input === "object" && !Array.isArray(input);
+}

package/src/session/messages/SessionUserContext.ts

@@ -0,0 +1,47 @@
+/**
+ * Session User Context Part 的校验与模型标记渲染。
+ *
+ * canonical Message 始终保存原始 tag 与 context；只有进入模型上下文时才生成 XML 风格标记，
+ * 避免持久化层与具体模型提示格式互相耦合。
+ */
+
+/** Session Context 标签允许使用的稳定名称格式。 */
+const SESSION_CONTEXT_TAG_PATTERN = /^[a-z][a-z0-9_-]*$/u;
+
+/** 校验并规范化 Session Context 标签。 */
+export function normalize_session_context_tag(tag_input: unknown): string {
+  const tag = typeof tag_input === "string" ? tag_input.trim() : "";
+  if (!SESSION_CONTEXT_TAG_PATTERN.test(tag)) {
+    throw new Error(
+      "Session context tag must start with a lowercase letter and contain only lowercase letters, numbers, underscores, or hyphens",
+    );
+  }
+  return tag;
+}
+
+/** 校验 Session Context 正文，同时保留调用方提供的原始空白。 */
+export function normalize_session_context_content(context_input: unknown): string {
+  const context = typeof context_input === "string" ? context_input : "";
+  if (!context.trim()) {
+    throw new Error("Session context content must not be empty");
+  }
+  return context;
+}
+
+/** 把 canonical Context Part 安全渲染为模型可消费的 XML 风格文本。 */
+export function render_session_user_context(
+  tag_input: unknown,
+  context_input: unknown,
+): string {
+  const tag = normalize_session_context_tag(tag_input);
+  const context = normalize_session_context_content(context_input);
+  return `<${tag}>${escape_xml_text(context)}</${tag}>`;
+}
+
+/** 转义 XML 文本节点中的结构字符，防止正文提前闭合或插入标签。 */
+function escape_xml_text(value: string): string {
+  return value
+    .replace(/&/gu, "&amp;")
+    .replace(/</gu, "&lt;")
+    .replace(/>/gu, "&gt;");
+}

package/src/session/messages/SessionUserMessage.ts

@@ -0,0 +1,88 @@
+/**
+ * Session User Message 与公开输入 Part 的 canonical 转换规则。
+ *
+ * 本模块只进行确定性数据归一化，不持有 Message、Store 或 Session 状态。
+ */
+
+import type {
+  SessionAgentContent,
+  SessionUserContent,
+} from "@downcity/type";
+import type { SessionUserMessagePart } from "@downcity/type";
+import { to_session_json_value } from "@/session/messages/SessionJsonValue.js";
+import {
+  normalize_session_context_content,
+  normalize_session_context_tag,
+} from "@/session/messages/SessionUserContext.js";
+
+/** 把 Downcity Session User parts 归一为 canonical User parts。 */
+export function normalize_session_user_parts(
+  parts: SessionUserContent[] | null | undefined,
+): SessionUserMessagePart[] {
+  if (!Array.isArray(parts)) return [];
+  return parts.flatMap<SessionUserMessagePart>((part, index) => {
+    if (part.type === "text") {
+      return [{
+        part_id: `user-text:${index + 1}`,
+        sequence: index + 1,
+        type: "text",
+        text: part.text,
+      }];
+    }
+    if (part.type === "context") {
+      return [{
+        part_id: `user-context:${index + 1}`,
+        sequence: index + 1,
+        type: "context",
+        tag: normalize_session_context_tag(part.tag),
+        context: normalize_session_context_content(part.context),
+      }];
+    }
+    if (part.type === "file") {
+      return [{
+        part_id: `user-file:${index + 1}`,
+        sequence: index + 1,
+        type: "file",
+        url: part.url,
+        media_type: part.media_type,
+        ...(part.filename ? { filename: part.filename } : {}),
+      }];
+    }
+    return [{
+      part_id: `user-data:${index + 1}`,
+      sequence: index + 1,
+      type: "data",
+      data_type: part.data_type,
+      data: to_session_json_value(part.data),
+      ...(part.data_id ? { data_id: part.data_id } : {}),
+    }];
+  });
+}
+
+/** 校验直接写入的 canonical User Parts，并保留已有 Part identity。 */
+export function normalize_canonical_session_user_parts(
+  parts: readonly SessionUserMessagePart[],
+): SessionUserMessagePart[] {
+  return parts.map((part, index) => {
+    const canonical = { ...structuredClone(part), sequence: index + 1 };
+    if (canonical.type !== "context") return canonical;
+    return {
+      ...canonical,
+      tag: normalize_session_context_tag(canonical.tag),
+      context: normalize_session_context_content(canonical.context),
+    };
+  });
+}
+
+/** 判断 Assistant 结果中是否包含可持久化内容。 */
+export function has_assistant_result_content(
+  parts: readonly SessionAgentContent[],
+): boolean {
+  return parts.some((part) => {
+    if (part.type === "text") return Boolean(part.text.trim());
+    if (part.type === "file") {
+      return Boolean(part.media_type.trim() && part.url.trim());
+    }
+    return Boolean(part.data_type.trim());
+  });
+}

package/src/session/preview/SessionMessagePreview.ts

@@ -10,9 +10,9 @@ import {
   extract_session_message_text,
   resolve_session_assistant_visible_text,
 } from "@/session/messages/SessionMessageText.js";
-import type { SessionMessage } from "@/types/session/SessionMessage.js";
+import type { SessionMessage } from "@downcity/type";
 
-function extract_assistant_tool_summary(message: Extract<SessionMessage, { type: "assistant" }>): string {
+function extract_assistant_tool_summary(message: Extract<SessionMessage, { role: "agent" }>): string {
   const tool_names = new Set<string>();
   for (const part of message.parts) {
     if (part.type !== "tool") continue;
@@ -30,16 +30,33 @@ function extract_assistant_tool_summary(message: Extract<SessionMessage, { type:
 export function resolve_session_message_preview(
   message: SessionMessage,
 ): string {
-  if (message.type === "action") {
-    return message.description
-      ? `${message.title}\n${message.description}`
-      : message.title;
-  }
-  if (message.type === "error") return message.message;
   const plain_text = extract_session_message_text(message);
   if (plain_text) return plain_text;
-  if (message.type !== "assistant") return "";
+  if (message.role !== "agent") return "";
 
   const user_visible = resolve_session_assistant_visible_text(message).trim();
-  return user_visible || extract_assistant_tool_summary(message);
+  if (user_visible) return user_visible;
+  for (const part of message.parts) {
+    switch (part.type) {
+      case "action":
+        return part.description ? `${part.title}\n${part.description}` : part.title;
+      case "error":
+        return part.message;
+      case "text":
+      case "reasoning":
+      case "tool":
+      case "interaction":
+      case "file":
+      case "data":
+        break;
+      default:
+        assert_never(part);
+    }
+  }
+  return extract_assistant_tool_summary(message);
+}
+
+/** canonical Agent Part 增加成员时强制预览投影显式处理。 */
+function assert_never(value: never): never {
+  throw new Error(`Unsupported preview Session Part: ${String((value as { type?: unknown }).type)}`);
 }

package/src/session/runtime/SessionEventHub.ts

@@ -10,7 +10,7 @@ import type {
   SessionMutation,
   SessionMutationSubscriber,
   SessionMutationUnsubscribe,
-} from "@/types/session/SessionMutation.js";
+} from "@downcity/type";
 
 /**
  * SessionEventHub：最小事件总线实现。

package/src/session/runtime/SessionModelRequestWarning.ts

@@ -0,0 +1,29 @@
+/**
+ * Session 模型请求 Warning 投影模块。
+ *
+ * 本模块是内部模型请求失败与公开 Session Mutation 之间的唯一转换边界。
+ */
+
+import type { ModelRequestFailureNotice } from "@downcity/type";
+import type { SessionModelRequestWarningMutation } from "@downcity/type";
+import { generate_id } from "@/utils/Id.js";
+
+/** 构造公开 Session 模型请求 Warning Mutation。 */
+export function create_session_model_request_warning(input: {
+  /** 当前 Session 的稳定标识。 */
+  session_id: string;
+  /** 当前模型请求所属 Turn；后台 Session 请求允许为空。 */
+  turn_id?: string;
+  /** 模型请求执行器产生的内部失败通知。 */
+  notice: ModelRequestFailureNotice;
+}): SessionModelRequestWarningMutation {
+  return {
+    mutation_id: generate_id(),
+    variant: "warning",
+    type: "model_request",
+    session_id: input.session_id,
+    created_at: Date.now(),
+    ...(input.turn_id ? { turn_id: input.turn_id } : {}),
+    ...input.notice,
+  };
+}

package/src/session/runtime/SessionTitleTask.ts

@@ -18,13 +18,13 @@ export interface SessionTitleTaskOptions {
   session_id: string;
 
   /** 用于记录后台任务失败的统一日志器。 */
-  logger: Logger;
+  logger?: Logger;
 }
 
 /** Session 标题后台任务协调器。 */
 export class SessionTitleTask {
   private readonly session_id: string;
-  private readonly logger: Logger;
+  private readonly logger?: Logger;
   private active_task: Promise<void> | null = null;
   private abort_controller: AbortController | null = null;
   private pending_runner: SessionTitleTaskRunner | null = null;
@@ -52,7 +52,7 @@ export class SessionTitleTask {
       .catch(async (error) => {
         if (abort_controller.signal.aborted) return;
         try {
-          await this.logger.log("warn", "[agent] session_title.task_failed", {
+          await this.logger?.log("warn", "[agent] session_title.task_failed", {
             session_id: this.session_id,
             error: error instanceof Error ? error.message : String(error),
           });