@downcity/agent 1.1.150 → 1.1.153

package/src/executor/tools/plugin/PluginToolBridge.ts

@@ -4,14 +4,16 @@
  * 关键点（中文）
  * - tool 层不直接持有 agent 或 plugin registry，只通过装配期注入的 AgentPlugins 调用 action。
  * - 如果 action 返回 AI SDK UIMessage，则抽取 file parts 并入最终 assistant 消息。
- * - 返回给模型的 tool result 只保留短摘要，避免 data URL 等大内容污染上下文。
+ * - 返回给模型的 tool result 只保留短摘要和本地绝对路径，避免 data URL 等大内容污染上下文。
  */
 
+import path from "node:path";
 import type { FileUIPart } from "ai";
 import type { JsonObject, JsonValue } from "@/types/common/Json.js";
 import type { AgentPlugins } from "@/plugin/types/Plugin.js";
 import type {
   PluginCallInput,
+  PluginCallToolFileResult,
   PluginCallToolResult,
 } from "@/executor/tools/plugin/types/PluginTool.js";
 import { materializeAssistantFileParts } from "@executor/messages/AssistantFileResource.js";
@@ -69,27 +71,57 @@ function extract_assistant_file_parts(data: JsonValue | undefined): FileUIPart[]
   return parts.filter(is_file_part);
 }
 
+/**
+ * 解析当前项目根目录，保持与 assistant 文件落盘逻辑一致。
+ */
+function resolve_project_root(project_root: string | undefined): string {
+  const raw = String(project_root || "").trim();
+  return path.resolve(raw || process.cwd());
+}
+
+/**
+ * 将 `resources://` URL 转成本机绝对路径。
+ */
+function resolve_resources_file_path(
+  project_root: string,
+  raw_url: string,
+): string {
+  const prefix = "resources://";
+  const raw = String(raw_url || "").trim();
+  if (!raw.startsWith(prefix)) return "";
+  const relative = raw.slice(prefix.length).replace(/^\/+/, "");
+  if (!relative) return "";
+
+  const file_path = path.resolve(project_root, relative);
+  const rel = path.relative(project_root, file_path);
+  if (rel === "" || rel.startsWith("..") || path.isAbsolute(rel)) return "";
+  return file_path;
+}
+
+/**
+ * 构建返回给模型和用户可见的文件摘要。
+ */
+function summarize_materialized_files(
+  parts: FileUIPart[],
+  project_root: string,
+): PluginCallToolFileResult[] {
+  return parts.map((part, index) => ({
+    index,
+    media_type: part.mediaType,
+    filename: typeof part.filename === "string" ? part.filename : "",
+    url: String(part.url || ""),
+    path: resolve_resources_file_path(project_root, String(part.url || "")),
+  }));
+}
+
 /**
  * 生成给模型读取的短摘要。
  */
-function summarize_action_data(data: JsonValue | undefined): JsonObject {
+function summarize_action_data(data: JsonValue | undefined): JsonObject | undefined {
   const message = to_json_object(data);
   const parts: unknown[] = Array.isArray(message?.parts) ? message.parts : [];
-  const file_parts = parts.filter(is_file_part);
   if (parts.length > 0) {
-    return {
-      kind: "ui_message",
-      role: typeof message?.role === "string" ? message.role : "assistant",
-      part_count: parts.length,
-      file_count: file_parts.length,
-      files: file_parts.map((part, index) => ({
-        index,
-        mediaType: part.mediaType,
-        filename: typeof part.filename === "string" ? part.filename : "",
-        // 关键点（中文）：不把 data URL 或长 URL 原样返回给模型，完整内容只进入 assistant file part。
-        has_url: Boolean(part.url),
-      })),
-    };
+    return undefined;
   }
   if (data === undefined) return {};
   return {
@@ -135,29 +167,33 @@ export async function invokePluginCallTool(
       action,
       payload,
     });
+    const project_root = resolve_project_root(getSessionRunContext()?.projectRoot);
     const raw_file_parts = result.success
       ? extract_assistant_file_parts(result.data)
       : [];
     const file_parts =
       raw_file_parts.length > 0
         ? await materializeAssistantFileParts({
-            projectRoot: getSessionRunContext()?.projectRoot,
+            projectRoot: project_root,
             parts: raw_file_parts,
           })
         : [];
+    const files = summarize_materialized_files(file_parts, project_root);
     if (file_parts.length > 0) {
       enqueueAssistantFileParts(file_parts);
     }
+    const data = summarize_action_data(result.data);
     return {
       success: result.success,
       plugin,
       action,
       assistant_file_count: file_parts.length,
+      ...(files.length > 0 ? { files } : {}),
       message:
         String(result.message || result.error || "").trim() ||
         (result.success ? "plugin action completed" : "plugin action failed"),
       ...(result.error ? { error: result.error } : {}),
-      data: summarize_action_data(result.data),
+      ...(data === undefined ? {} : { data }),
     };
   } catch (error) {
     return {

package/src/executor/tools/plugin/types/PluginTool.ts

@@ -20,6 +20,22 @@ export interface PluginCallInput {
   payload?: JsonObject;
 }
 
+/**
+ * plugin_call 产生的 assistant 文件摘要。
+ */
+export interface PluginCallToolFileResult {
+  /** 文件在本轮 assistant 文件列表中的顺序。 */
+  index: number;
+  /** 文件 MIME 类型，例如 `image/png`。 */
+  media_type: string;
+  /** 原始文件名；若上游未提供则为空字符串。 */
+  filename: string;
+  /** 持久化到历史消息中的资源 URL，通常为 `resources://.downcity/resources/...`。 */
+  url: string;
+  /** 当前机器可直接打开的绝对文件路径。 */
+  path: string;
+}
+
 /**
  * plugin_call 返回给模型的摘要结果。
  */
@@ -32,6 +48,8 @@ export interface PluginCallToolResult {
   action: string;
   /** 本次 action 产生并写入 assistant 消息的 file part 数量。 */
   assistant_file_count: number;
+  /** 本次 action 产生的文件摘要，包含可直接打开的绝对路径。 */
+  files?: PluginCallToolFileResult[];
   /** 人类可读消息。 */
   message: string;
   /** 错误信息。 */

package/src/executor/types/SessionRun.ts

@@ -4,7 +4,7 @@
  * 关键点（中文）
  * - `SessionRunInput` 表示上层会话入口输入（例如 context query）。
  * - `SessionExecuteInput` 表示 Executor 通过 Composer 装配后的中间运行态。
- * - 输出仅暴露 assistantMessage（UIMessage）。
+ * - 输出暴露可选 assistantMessage（UIMessage）。
  */
 
 import type { Tool, UIMessageChunk } from "ai";
@@ -94,8 +94,12 @@ export interface SessionRunResult {
 
   /**
    * 最终 assistant 消息。
+   *
+   * 关键点（中文）
+   * - stop/abort 且没有任何 assistant 内容时可以为空。
+   * - turn 状态通过 `success` / `error` 表达，不应伪造成 assistant 正文。
    */
-  assistantMessage: SessionMessageV1;
+  assistantMessage?: SessionMessageV1 | null;
 
   /**
    * 本轮执行结束后待写入长期历史的 user 消息。

package/src/session/browse/Browse.ts

@@ -32,15 +32,12 @@ import type {
 import type { SessionHistoryMetaV1 } from "@/executor/types/SessionHistoryMeta.js";
 import { pickLastSuccessfulChatSendText } from "@/executor/messages/UserVisibleText.js";
 import { getSdkAgentSessionMessagesPath } from "@/session/storage/Paths.js";
+import { getSdkAgentSessionMetaPath } from "@/session/storage/Paths.js";
 import { getSdkAgentSessionsRootDirPath } from "@/session/storage/Paths.js";
 import { getSdkAgentArchivedSessionsDirPath } from "@/session/storage/Paths.js";
 import { getSdkAgentArchivedSessionMessagesPath } from "@/session/storage/Paths.js";
 import { getSdkAgentArchivedSessionMetaPath } from "@/session/storage/Paths.js";
-import { readSessionMetadata } from "@/session/storage/Metadata.js";
 import { readSessionMetadataFromPath } from "@/session/storage/Metadata.js";
-import {
-  ensureSessionTitle,
-} from "@/session/SessionTitle.js";
 
 type AnyUiPart = UIMessagePart<Record<string, never>, Record<string, never>>;
 
@@ -479,7 +476,7 @@ export async function listAgentSessionSummaryPage(params: {
     const sessionId = decodeMaybe(entry.name);
     if (!sessionId) continue;
     const metadata = await readSessionMetadataFromPath({
-      filePath: getSdkAgentArchivedSessionMetaPath(
+      filePath: getSdkAgentSessionMetaPath(
         params.projectRoot,
         params.agentId,
         sessionId,
@@ -488,19 +485,17 @@ export async function listAgentSessionSummaryPage(params: {
       agentId: params.agentId,
     });
     const messages = await loadSessionMessagesFromPath(
-      getSdkAgentArchivedSessionMessagesPath(
+      getSdkAgentSessionMessagesPath(
         params.projectRoot,
         params.agentId,
         sessionId,
       ),
     );
-    // 关键点（中文）：归档 session 不再生成新 title，仅读取已有 meta。
-    const metadataWithTitle = metadata;
     const info = buildSessionInfo({
       projectRoot: params.projectRoot,
       agentId: params.agentId,
       sessionId,
-      metadata: metadataWithTitle,
+      metadata,
       messages,
       executing: params.executingSessionIds?.has(sessionId),
     });
@@ -575,27 +570,28 @@ export async function listArchivedAgentSessionSummaryPage(params: {
     if (!entry.isDirectory()) continue;
     const sessionId = decodeMaybe(entry.name);
     if (!sessionId) continue;
-    const metadata = await readSessionMetadata({
-      projectRoot: params.projectRoot,
-      agentId: params.agentId,
+    const metadata = await readSessionMetadataFromPath({
+      filePath: getSdkAgentArchivedSessionMetaPath(
+        params.projectRoot,
+        params.agentId,
+        sessionId,
+      ),
       sessionId,
+      agentId: params.agentId,
     });
     const messages = await loadSessionMessagesFromPath(
-      getSdkAgentSessionMessagesPath(params.projectRoot, params.agentId, sessionId),
+      getSdkAgentArchivedSessionMessagesPath(
+        params.projectRoot,
+        params.agentId,
+        sessionId,
+      ),
     );
-    const metadataWithTitle = metadata.title
-      ? metadata
-      : await ensureSessionTitle({
-          projectRoot: params.projectRoot,
-          agentId: params.agentId,
-          sessionId,
-          messages,
-        });
+    // 关键点（中文）：归档 session 不再生成新 title，仅读取归档目录内已有 meta。
     const info = buildSessionInfo({
       projectRoot: params.projectRoot,
       agentId: params.agentId,
       sessionId,
-      metadata: metadataWithTitle,
+      metadata,
       messages,
       executing: false,
     });

package/src/session/runtime/SessionPromptRuntime.ts

@@ -106,7 +106,7 @@ export interface SessionPromptRuntimeOptions {
   }) => Promise<{
     text: string;
     success: boolean;
-    assistantMessage: SessionMessageV1;
+    assistantMessage?: SessionMessageV1 | null;
     error?: string;
   }>;
 
@@ -233,7 +233,9 @@ export class SessionPromptRuntime {
           turnId,
           text: result.text,
           success: stopped ? false : result.success,
-          assistantMessage: result.assistantMessage,
+          ...(result.assistantMessage
+            ? { assistantMessage: result.assistantMessage }
+            : {}),
           ...(stopped
             ? { error: TURN_STOPPED_MESSAGE }
             : result.error ? { error: result.error } : {}),

package/src/session/services/SessionStateService.ts

@@ -289,7 +289,7 @@ export class SessionStateService {
    * 持久化最终 assistant 结果。
    */
   async persist_assistant_result(
-    assistant_message: SessionMessageV1,
+    assistant_message?: SessionMessageV1 | null,
   ): Promise<void> {
     await persistSdkAssistantResult({
       projectRoot: this.project_root,

package/src/session/services/SessionTurnService.ts

@@ -146,7 +146,7 @@ export class SessionTurnService {
   }): Promise<{
     text: string;
     success: boolean;
-    assistantMessage: SessionMessageV1;
+    assistantMessage?: SessionMessageV1 | null;
     error?: string;
   }> {
     const tool_name_by_call_id = new Map<string, string>();
@@ -214,9 +214,13 @@ export class SessionTurnService {
       result.deferredPersistedUserMessages,
     );
     return {
-      text: extractTextFromUiMessage(result.assistantMessage),
+      text: result.assistantMessage
+        ? extractTextFromUiMessage(result.assistantMessage)
+        : "",
       success: result.success,
-      assistantMessage: result.assistantMessage,
+      ...(result.assistantMessage
+        ? { assistantMessage: result.assistantMessage }
+        : {}),
       ...(result.error ? { error: result.error } : {}),
     };
   }

package/src/session/storage/Persistence.ts

@@ -60,8 +60,12 @@ export interface PersistSdkAssistantResultParams
   };
   /**
    * 本轮执行得到的 assistant 消息。
+   *
+   * 关键点（中文）
+   * - stop/abort 且没有 assistant 内容时允许为空。
+   * - 为空时仅刷新 metadata，不写入伪造 assistant 正文。
    */
-  assistantMessage: SessionMessageV1;
+  assistantMessage?: SessionMessageV1 | null;
 }
 
 /**
@@ -104,7 +108,9 @@ export async function persistSdkAssistantResult(
   await persistAssistantResult({
     writer: params.executor,
     assistantMessage: params.assistantMessage,
-    fallbackText: extractTextFromUiMessage(params.assistantMessage),
+    fallbackText: params.assistantMessage
+      ? extractTextFromUiMessage(params.assistantMessage)
+      : undefined,
   });
   await touchSessionMetadata(params);
 }

package/src/types/agent/SessionTypes.ts

@@ -212,8 +212,8 @@ export interface AgentSessionSummary {
    *
    * 说明（中文）
    * - 标题持久化在 session `meta.json` 顶层。
-   * - 首条用户消息出现后，SDK 会优先生成标题，失败时回退到首条用户消息截断。
-   * - 空 session 可能暂时没有标题，调用方可回退到 `sessionId`。
+   * - SDK 只在模型成功生成标题时写入，不再从首条用户消息生成 fallback。
+   * - 标题允许为空，调用方需要展示占位文案时可自行回退到 `sessionId`。
    */
   title?: string;
   /**