@downcity/agent 1.1.43 → 1.1.62

package/src/session/SessionTitle.ts

@@ -0,0 +1,192 @@
+/**
+ * SDK Session 标题生成与持久化辅助。
+ *
+ * 关键点（中文）
+ * - session title 是 `meta.json` 顶层字段，列表与详情都以它为准。
+ * - 首次用户消息出现后优先使用模型生成标题，失败时回退到首条用户消息截断。
+ * - 老 session 缺失 title 时可在读取列表/详情时补写 fallback title。
+ */
+
+import { generateText, type LanguageModel } from "ai";
+import type { SessionHistoryMetaV1 } from "@/executor/types/SessionHistoryMeta.js";
+import type { SessionMessageV1 } from "@/executor/types/SessionMessages.js";
+import {
+  normalizeSessionTitle,
+  readSessionMetadata,
+  writeSessionMetadata,
+} from "@/session/storage/Metadata.js";
+
+const FALLBACK_SESSION_TITLE_MAX_CHARS = 60;
+const GENERATED_SESSION_TITLE_MAX_CHARS = 24;
+
+/**
+ * 标题持久化参数。
+ */
+export interface EnsureSessionTitleParams {
+  /**
+   * 当前项目根目录。
+   */
+  projectRoot: string;
+
+  /**
+   * 当前 agent 稳定标识。
+   */
+  agentId: string;
+
+  /**
+   * 当前 sessionId。
+   */
+  sessionId: string;
+
+  /**
+   * 当前 session 已落盘消息。
+   */
+  messages: SessionMessageV1[];
+
+  /**
+   * 可选模型实例；传入时会尝试生成更短标题。
+   */
+  model?: LanguageModel;
+
+  /**
+   * 是否允许调用模型生成标题。
+   */
+  generate?: boolean;
+}
+
+function truncateTitle(input: string, maxChars: number): string {
+  const title = String(input || "").replace(/\s+/g, " ").trim();
+  if (!title) return "";
+  if (title.length <= maxChars) return title;
+  return title.slice(0, maxChars).trimEnd();
+}
+
+function extractTextFromMessage(message: SessionMessageV1): string {
+  if (!Array.isArray(message.parts)) return "";
+  const texts: string[] = [];
+  for (const part of message.parts) {
+    if (!part || typeof part !== "object") continue;
+    const textPart = part as { type?: unknown; text?: unknown };
+    if (textPart.type !== "text" || typeof textPart.text !== "string") continue;
+    const text = textPart.text.trim();
+    if (!text) continue;
+    texts.push(text);
+  }
+  return texts.join("\n").trim();
+}
+
+function resolveFirstUserText(messages: SessionMessageV1[]): string {
+  for (const message of messages) {
+    if (message.role !== "user") continue;
+    const text = extractTextFromMessage(message);
+    if (text) return text;
+  }
+  return "";
+}
+
+function normalizeGeneratedTitle(input: string): string | undefined {
+  const firstLine = String(input || "")
+    .split("\n")
+    .map((line) => line.trim())
+    .find(Boolean);
+  const title = normalizeSessionTitle(
+    String(firstLine || "")
+      .replace(/^["'`“”‘’]+|["'`“”‘’]+$/g, "")
+      .replace(/^标题[:：]\s*/i, "")
+      .trim(),
+  );
+  return title
+    ? truncateTitle(title, GENERATED_SESSION_TITLE_MAX_CHARS)
+    : undefined;
+}
+
+/**
+ * 从首条用户消息推导 fallback 标题。
+ */
+export function resolveFallbackSessionTitle(
+  messages: SessionMessageV1[],
+): string | undefined {
+  const firstUserText = resolveFirstUserText(messages);
+  const title = truncateTitle(
+    firstUserText,
+    FALLBACK_SESSION_TITLE_MAX_CHARS,
+  );
+  return normalizeSessionTitle(title);
+}
+
+async function generateSessionTitle(input: {
+  /**
+   * 当前模型实例。
+   */
+  model: LanguageModel;
+
+  /**
+   * 首条用户消息文本。
+   */
+  firstUserText: string;
+}): Promise<string | undefined> {
+  try {
+    const result = await generateText({
+      model: input.model,
+      system:
+        "你负责为一段会话生成极简标题。只输出标题本身，不要解释，不要使用引号。",
+      prompt: [
+        "根据下面这条用户首条消息，生成一个简短的会话标题。",
+        "要求：3 到 12 个汉字或 2 到 6 个英文词；不要句号；不要前缀。",
+        "",
+        input.firstUserText,
+      ].join("\n"),
+    });
+    return normalizeGeneratedTitle(result.text);
+  } catch {
+    // 关键点（中文）：标题生成失败不能影响 session 主流程。
+    return undefined;
+  }
+}
+
+/**
+ * 确保当前 session meta 中持久化 title。
+ */
+export async function ensureSessionTitle(
+  input: EnsureSessionTitleParams,
+): Promise<SessionHistoryMetaV1> {
+  const current = await readSessionMetadata(input);
+  if (current.title) return current;
+
+  const firstUserText = resolveFirstUserText(input.messages);
+  const fallbackTitle = resolveFallbackSessionTitle(input.messages);
+  if (!fallbackTitle) return current;
+
+  const fallbackMeta: SessionHistoryMetaV1 = {
+    ...current,
+    title: fallbackTitle,
+  };
+  await writeSessionMetadata({
+    projectRoot: input.projectRoot,
+    agentId: input.agentId,
+    sessionId: input.sessionId,
+    meta: fallbackMeta,
+  });
+
+  if (input.generate !== true || !input.model || !firstUserText) {
+    return fallbackMeta;
+  }
+
+  const generatedTitle = await generateSessionTitle({
+    model: input.model,
+    firstUserText,
+  });
+  if (!generatedTitle) return fallbackMeta;
+
+  const generatedMeta: SessionHistoryMetaV1 = {
+    ...fallbackMeta,
+    title: generatedTitle,
+  };
+  await writeSessionMetadata({
+    projectRoot: input.projectRoot,
+    agentId: input.agentId,
+    sessionId: input.sessionId,
+    meta: generatedMeta,
+  });
+  return generatedMeta;
+}

package/src/session/browse/Browse.ts

@@ -2,7 +2,8 @@
  * SDK Session 浏览辅助。
  *
  * 关键点（中文）
- * - 统一负责 session 列表摘要、session 详情与 history 分页的只读投影逻辑。
+ * - 统一负责 session 列表摘要、session 详情与 history 分页的投影逻辑。
+ * - 老 session 缺失持久化 title 时，会在列表读取阶段补写 fallback title。
  * - 面向 SDK / RemoteAgent / HTTP route 复用，避免在多个入口重复拼列表与分页语义。
  * - 这里不持有运行态状态；执行状态等动态信息通过调用参数显式注入。
  */
@@ -33,6 +34,10 @@ import { pickLastSuccessfulChatSendText } from "@/executor/messages/UserVisibleT
 import { getSdkAgentSessionMessagesPath } from "@/session/storage/Paths.js";
 import { getSdkAgentSessionsRootDirPath } from "@/session/storage/Paths.js";
 import { readSessionMetadata } from "@/session/storage/Metadata.js";
+import {
+  ensureSessionTitle,
+  resolveFallbackSessionTitle,
+} from "@/session/SessionTitle.js";
 
 type AnyUiPart = UIMessagePart<Record<string, never>, Record<string, never>>;
 
@@ -184,14 +189,7 @@ export function resolveSessionMessagePreview(message: SessionMessageV1): string
  * 推导当前 session 的可读标题。
  */
 export function resolveSessionTitle(messages: SessionMessageV1[]): string | undefined {
-  for (const message of messages) {
-    if (message.role !== "user") continue;
-    const preview = resolveSessionMessagePreview(message);
-    if (!preview) continue;
-    return truncateText(preview, 80);
-  }
-  const fallback = messages[0] ? resolveSessionMessagePreview(messages[0]) : "";
-  return fallback ? truncateText(fallback, 80) : undefined;
+  return resolveFallbackSessionTitle(messages);
 }
 
 function resolveToolName(part: ToolPartCompatShape, aiToolName?: string): string {
@@ -361,7 +359,10 @@ export function buildSessionInfo(
         180,
       )
     : undefined;
-  const title = resolveSessionTitle(input.messages);
+  const title =
+    typeof input.metadata.title === "string" && input.metadata.title.trim()
+      ? input.metadata.title.trim()
+      : undefined;
   return {
     agentId: input.agentId,
     sessionId: input.sessionId,
@@ -374,8 +375,8 @@ export function buildSessionInfo(
     ...(typeof input.metadata.updatedAt === "number"
       ? { updatedAt: input.metadata.updatedAt }
       : {}),
-    ...(input.metadata.sdkConfig?.modelLabel
-      ? { modelLabel: input.metadata.sdkConfig.modelLabel }
+    ...(input.metadata.modelLabel
+      ? { modelLabel: input.metadata.modelLabel }
       : {}),
     ...(typeof input.metadata.timezone === "string" && input.metadata.timezone.trim()
       ? { timezone: input.metadata.timezone.trim() }
@@ -470,11 +471,19 @@ export async function listAgentSessionSummaryPage(params: {
     const messages = await loadSessionMessagesFromPath(
       getSdkAgentSessionMessagesPath(params.projectRoot, params.agentId, sessionId),
     );
+    const metadataWithTitle = metadata.title
+      ? metadata
+      : await ensureSessionTitle({
+          projectRoot: params.projectRoot,
+          agentId: params.agentId,
+          sessionId,
+          messages,
+        });
     const info = buildSessionInfo({
       projectRoot: params.projectRoot,
       agentId: params.agentId,
       sessionId,
-      metadata,
+      metadata: metadataWithTitle,
       messages,
       executing: params.executingSessionIds?.has(sessionId),
     });

package/src/session/index.ts

@@ -10,7 +10,6 @@ export { Session } from "./Session.js";
 
 export {
   getSdkAgentDirPath,
-  getSdkAgentRpcEndpointPath,
   getSdkAgentSessionArchiveDirPath,
   getSdkAgentSessionDirPath,
   getSdkAgentSessionMessagesDirPath,
@@ -22,11 +21,16 @@ export {
 } from "./storage/Paths.js";
 export {
   inferModelLabel,
+  normalizeSessionTitle,
   patchSessionModelLabel,
   readSessionMetadata,
   resolveSystemTimezone,
   writeSessionMetadata,
 } from "./storage/Metadata.js";
+export {
+  ensureSessionTitle,
+  resolveFallbackSessionTitle,
+} from "./SessionTitle.js";
 export {
   persistSdkAssistantResult,
   touchSessionMetadata,

package/src/session/storage/Metadata.ts

@@ -8,10 +8,7 @@
 
 import fs from "fs-extra";
 import type { LanguageModel } from "ai";
-import type {
-  SessionHistoryMetaV1,
-  SessionHistorySdkConfigV1,
-} from "@/executor/types/SessionHistoryMeta.js";
+import type { SessionHistoryMetaV1 } from "@/executor/types/SessionHistoryMeta.js";
 import { getSdkAgentSessionMetaPath } from "@/session/storage/Paths.js";
 
 type ReadSessionMetadataInput = {
@@ -36,6 +33,14 @@ function normalizeModelLabel(input: unknown): string | undefined {
   return label || undefined;
 }
 
+/**
+ * 归一化 session 标题。
+ */
+export function normalizeSessionTitle(input: unknown): string | undefined {
+  const title = typeof input === "string" ? input.trim() : "";
+  return title || undefined;
+}
+
 /**
  * 读取当前系统时区。
  */
@@ -103,27 +108,11 @@ export async function readSessionMetadata(
         typeof raw.updatedAt === "number" && Number.isFinite(raw.updatedAt)
           ? raw.updatedAt
           : 0,
-      pinnedSkillIds: Array.isArray(raw.pinnedSkillIds)
-        ? raw.pinnedSkillIds
-            .map((item) => (typeof item === "string" ? item.trim() : ""))
-            .filter(Boolean)
-        : [],
-      ...(typeof raw.lastArchiveId === "string" && raw.lastArchiveId.trim()
-        ? { lastArchiveId: raw.lastArchiveId.trim() }
-        : {}),
-      ...(typeof raw.keepLastMessages === "number" &&
-      Number.isFinite(raw.keepLastMessages)
-        ? { keepLastMessages: raw.keepLastMessages }
-        : {}),
-      ...(typeof raw.maxInputTokensApprox === "number" &&
-      Number.isFinite(raw.maxInputTokensApprox)
-        ? { maxInputTokensApprox: raw.maxInputTokensApprox }
-        : {}),
-      ...(typeof raw.compactRatio === "number" && Number.isFinite(raw.compactRatio)
-        ? { compactRatio: raw.compactRatio }
+      ...(normalizeSessionTitle(raw.title)
+        ? { title: normalizeSessionTitle(raw.title) }
         : {}),
-      ...(raw.sdkConfig && typeof raw.sdkConfig === "object"
-        ? { sdkConfig: raw.sdkConfig as SessionHistorySdkConfigV1 }
+      ...(normalizeModelLabel(raw.modelLabel)
+        ? { modelLabel: normalizeModelLabel(raw.modelLabel) }
         : {}),
     };
   } catch {
@@ -134,7 +123,6 @@ export async function readSessionMetadata(
       createdAt: Date.now(),
       timezone: resolveSystemTimezone(),
       updatedAt: 0,
-      pinnedSkillIds: [],
     };
   }
 }
@@ -181,10 +169,7 @@ export async function patchSessionModelLabel(
     updatedAt: Date.now(),
     ...(modelLabel
       ? {
-          sdkConfig: {
-            ...(current.sdkConfig || {}),
-            modelLabel,
-          },
+          modelLabel,
         }
       : {}),
   };

package/src/session/storage/Paths.ts

@@ -114,13 +114,3 @@ export function getSdkAgentSessionArchiveDirPath(
     "archive",
   );
 }
-
-/**
- * 单个 agent 的本地 RPC socket 路径。
- */
-export function getSdkAgentRpcEndpointPath(
-  projectRoot: string,
-  agentId: string,
-): string {
-  return path.join(getSdkAgentDirPath(projectRoot, agentId), "agent.rpc.sock");
-}

package/src/session/storage/Persistence.ts

@@ -83,10 +83,7 @@ export async function touchSessionMetadata(
     updatedAt: Date.now(),
     ...(params.sessionConfig.modelLabel
       ? {
-          sdkConfig: {
-            ...(current.sdkConfig || {}),
-            modelLabel: params.sessionConfig.modelLabel,
-          },
+          modelLabel: params.sessionConfig.modelLabel,
         }
       : {}),
   };

package/src/types/agent/AgentTypes.ts

@@ -9,8 +9,8 @@
 
 import type { LanguageModel, Tool } from "ai";
 import type { BasePlugin } from "@/plugin/core/BasePlugin.js";
-import type { LocalRpcServerHandle } from "@/types/runtime/rpc/LocalRpc.js";
-import type { ServerInstance } from "@/runtime/server/http/Server.js";
+import type { AgentModel } from "@/model/CityModelAdapter.js";
+import type { RpcServerInstance } from "@/rpc/Server.js";
 import type { SessionMessageV1 } from "@/executor/types/SessionMessages.js";
 import type {
   AgentSessionSubscriber,
@@ -19,6 +19,8 @@ import type {
 import type { AgentSessionPromptInput } from "@/types/sdk/AgentSessionPrompt.js";
 import type { AgentSessionTurnHandle } from "@/types/sdk/AgentSessionTurn.js";
 
+export type { AgentModel } from "@/model/CityModelAdapter.js";
+
 /**
  * 本地 Agent 构造参数。
  */
@@ -60,10 +62,11 @@ export interface AgentOptions {
    * 当前 agent 为新建 session 提供的默认模型实例。
    *
    * 关键点（中文）
-   * - SDK 仍不负责“选择哪个模型”，这里只接收宿主已经创建好的 `LanguageModel`。
+   * - SDK 仍不负责“选择哪个模型”，这里只接收宿主已经创建好的模型实例。
+   * - 支持 AI SDK `LanguageModel`，也支持 City City 返回的 `CityModel`。
    * - 该模型会作为 session 首次执行前的默认注入值。
    */
-  model?: LanguageModel;
+  model?: AgentModel;
 
   /**
    * 当前 agent 显式持有的插件实例集合。
@@ -77,12 +80,12 @@ export interface AgentOptions {
   plugins?: BasePlugin[];
 
   /**
-   * 当前 agent 实例可见的环境变量快照。
+   * 当前 agent 的显式环境变量覆盖项。
    *
    * 关键点（中文）
-   * - 这里传入的是已经在宿主侧完成合并的最终环境变量集合。
-   * - SDK 不再区分 global env 与 agent env；如需区分，应由更上层在传入前自行处理。
-   * - 该快照会参与配置解析与运行时上下文装配，但不会回写到宿主环境。
+   * - 这里表示宿主显式注入给 agent 的基础 env。
+   * - `Agent` 会在这份基础 env 之上继续叠加项目 `.env`。
+   * - 覆盖后的最终 env 会参与配置解析与运行时上下文装配，但不会回写到宿主环境。
    */
   env?: Record<string, string>;
 
@@ -93,23 +96,14 @@ export interface AgentOptions {
  */
 export interface AgentStartOptions {
   /**
-   * 是否启动 HTTP 服务。
+   * 是否启动本机 RPC 服务。
    *
    * 关键点（中文）
    * - `false` 表示不启动。
    * - 传对象时会按给定 host/port 启动。
    * - 省略时默认不启动，避免 SDK 本地嵌入场景误开端口。
    */
-  http?: false | AgentHttpStartOptions;
-
-  /**
-   * 是否启动本地 RPC 服务。
-   *
-   * 关键点（中文）
-   * - `true` 时启动主 local RPC server。
-   * - 省略或 `false` 时不启动。
-   */
-  rpc?: boolean;
+  rpc?: false | AgentRpcStartOptions;
 
   /**
    * 是否启动当前 agent 的 plugins。
@@ -126,12 +120,7 @@ export interface AgentStartOptions {
  */
 export interface AgentStopResult {
   /**
-   * 本次是否实际停止了 HTTP 服务。
-   */
-  httpStopped: boolean;
-
-  /**
-   * 本次是否实际停止了本地 RPC 服务。
+   * 本次是否实际停止了本机 RPC 服务。
    */
   rpcStopped: boolean;
 
@@ -146,12 +135,7 @@ export interface AgentStopResult {
  */
 export interface AgentStartResult {
   /**
-   * 当前 agent 是否已启动 HTTP 服务。
-   */
-  http?: AgentHttpBinding;
-
-  /**
-   * 当前 agent 是否已启动本地 RPC 服务。
+   * 当前 agent 是否已启动本机 RPC 服务。
    */
   rpc?: AgentRpcBinding;
 
@@ -162,28 +146,28 @@ export interface AgentStartResult {
 }
 
 /**
- * Agent HTTP 启动参数。
+ * Agent RPC 启动参数。
  */
-export interface AgentHttpStartOptions {
+export interface AgentRpcStartOptions {
   /**
-   * HTTP 监听主机。
+   * RPC 监听主机。
    */
   host?: string;
 
   /**
-   * HTTP 监听端口。
+   * RPC 监听端口。
    */
   port?: number;
 }
 
 /**
- * Agent HTTP 绑定信息。
+ * Agent RPC 绑定信息。
  */
-export interface AgentHttpBinding {
+export interface AgentRpcBinding {
   /**
-   * 对外访问地址。
+   * 远程访问地址。
    */
-  baseUrl: string;
+  url: string;
 
   /**
    * 当前 host。
@@ -196,24 +180,9 @@ export interface AgentHttpBinding {
   port: number;
 
   /**
-   * HTTP server 句柄。
+   * RPC server 句柄。
    */
-  server: ServerInstance;
-}
-
-/**
- * Agent RPC 绑定信息。
- */
-export interface AgentRpcBinding {
-  /**
-   * 当前本地 RPC endpoint。
-   */
-  endpoint: string;
-
-  /**
-   * 本地 RPC server 句柄。
-   */
-  server: LocalRpcServerHandle;
+  server: RpcServerInstance;
 }
 
 /**
@@ -221,11 +190,12 @@ export interface AgentRpcBinding {
  */
 export interface RemoteAgentOptions {
   /**
-   * 远程 SDK HTTP 基础地址。
+   * 远程 agent 访问地址。
    *
-   * 例如：`http://127.0.0.1:15314`
+   * 例如：`https://city.example.com`、`http://127.0.0.1:15314`
+   * 或 `rpc://127.0.0.1:5314`
    */
-  baseUrl: string;
+  url: string;
 }
 
 /**
@@ -286,7 +256,7 @@ export interface AgentSessionSetInput {
    * - 这里接受运行中的模型实例，而不是模型 ID。
    * - 由于模型实例通常不可序列化，落盘只保留轻量可读标签用于展示。
    */
-  model?: LanguageModel;
+  model?: AgentModel;
 }
 
 /**
@@ -475,8 +445,9 @@ export interface AgentSessionSummary {
    * 当前 session 可读标题。
    *
    * 说明（中文）
-   * - 当前 SDK 不要求标题一定存在。
-   * - 若调用方需要展示列表标题，可优先使用这里；为空时再回退到 `sessionId`。
+   * - 标题持久化在 session `meta.json` 顶层。
+   * - 首条用户消息出现后，SDK 会优先生成标题，失败时回退到首条用户消息截断。
+   * - 空 session 可能暂时没有标题，调用方可回退到 `sessionId`。
    */
   title?: string;
 

package/src/types/config/AgentProject.ts

@@ -24,18 +24,19 @@ export interface AgentProjectInitializationInput {
   projectRoot: string;
 
   /**
-   * agent 展示名。
+   * agent 唯一标识。
    *
    * 关键点（中文）
-   * - 为空时会自动回退到目录名推导出的默认名称。
+   * - 为空时会自动回退到目录名推导出的默认 id。
+   * - 该字段会直接写入 `downcity.json.id`。
    */
-  agentName?: string;
+  id?: string;
 
   /**
    * 项目执行绑定配置。
    *
    * 说明（中文）
-   * - 绑定平台全局模型池中的模型 ID。
+   * - 绑定 City AIService 暴露的模型 ID。
    */
   execution: ExecutionBindingConfig;
 
@@ -71,9 +72,9 @@ export interface AgentProjectInitializationResult {
   projectRoot: string;
 
   /**
-   * 最终写入的 agent 名称。
+   * 最终写入的 agent id。
    */
-  agentName: string;
+  id: string;
 
   /**
    * 最终启用的 chat channels。