@downcity/agent 1.1.51 → 1.1.62

package/src/session/Session.ts

@@ -30,7 +30,6 @@ import {
   SessionSystemBuilder,
 } from "@/session/SessionSystemBuilder.js";
 import {
-  inferModelLabel,
   buildSessionHistoryPage,
   buildSessionInfo,
   patchSessionModelLabel,
@@ -62,6 +61,11 @@ import type { AgentSessionTurnHandle } from "@/types/sdk/AgentSessionTurn.js";
 import type { SessionUserMessageV1 } from "@/executor/types/SessionMessages.js";
 import { SessionEventHub } from "@/session/runtime/SessionEventHub.js";
 import { SessionPromptRuntime } from "@/session/runtime/SessionPromptRuntime.js";
+import {
+  inferAgentModelLabel,
+  normalizeAgentModel,
+} from "@/model/CityModelAdapter.js";
+import { ensureSessionTitle } from "@/session/SessionTitle.js";
 
 type SessionOptions = {
   /**
@@ -257,8 +261,8 @@ export class Session implements AgentSession {
       this.createdAt = createdAt;
       this.timezone = timezone;
       this.sessionConfig = {
-        ...(metadata.sdkConfig?.modelLabel
-          ? { modelLabel: metadata.sdkConfig.modelLabel }
+        ...(metadata.modelLabel
+          ? { modelLabel: metadata.modelLabel }
           : {}),
       };
       return this;
@@ -280,8 +284,8 @@ export class Session implements AgentSession {
    */
   async set(input: AgentSessionSetInput): Promise<void> {
     if (input.model) {
-      this.sessionConfig.model = input.model;
-      this.sessionConfig.modelLabel = inferModelLabel(input.model);
+      this.sessionConfig.model = normalizeAgentModel(input.model);
+      this.sessionConfig.modelLabel = inferAgentModelLabel(input.model);
       this.executor.clearExecutor();
     }
     await patchSessionModelLabel({
@@ -333,6 +337,7 @@ export class Session implements AgentSession {
     await this.executor.appendUserMessage({
       text: String(input.text || "").trim(),
     });
+    await this.ensureTitleFromHistory({ generate: true });
     await this.touchMetadata();
   }
 
@@ -363,11 +368,19 @@ export class Session implements AgentSession {
       }),
       this.historyStore.list(),
     ]);
+    const metadataWithTitle = metadata.title
+      ? metadata
+      : await ensureSessionTitle({
+          projectRoot: this.projectRoot,
+          agentId: this.agentId,
+          sessionId: this.id,
+          messages,
+        });
     return buildSessionInfo({
       projectRoot: this.projectRoot,
       agentId: this.agentId,
       sessionId: this.id,
-      metadata,
+      metadata: metadataWithTitle,
       messages,
       executing: this.isExecuting(),
     });
@@ -477,6 +490,7 @@ export class Session implements AgentSession {
     for (const message of forkMessages) {
       await forked.historyStore.append(message);
     }
+    await forked.ensureTitleFromHistory({ generate: true });
     await forked.touchMetadata();
     return forked;
   }
@@ -503,6 +517,8 @@ export class Session implements AgentSession {
       },
       appendUserMessage: async (messageParams) => {
         await this.executor.appendUserMessage(messageParams);
+        await this.ensureTitleFromHistory({ generate: true });
+        await this.touchMetadata();
       },
       appendAssistantMessage: async (messageParams) => {
         await this.executor.appendAssistantMessage(messageParams);
@@ -558,6 +574,23 @@ export class Session implements AgentSession {
     });
   }
 
+  private async ensureTitleFromHistory(input?: {
+    /**
+     * 是否允许调用模型生成标题。
+     */
+    generate?: boolean;
+  }): Promise<void> {
+    const messages = await this.historyStore.list();
+    await ensureSessionTitle({
+      projectRoot: this.projectRoot,
+      agentId: this.agentId,
+      sessionId: this.id,
+      messages,
+      ...(input?.generate ? { model: this.sessionConfig.model } : {}),
+      generate: input?.generate === true,
+    });
+  }
+
   private async persistAssistantResult(
     assistantMessage: SessionMessageV1,
   ): Promise<void> {
@@ -583,6 +616,7 @@ export class Session implements AgentSession {
     await this.executor.appendUserMessage({
       message,
     });
+    await this.ensureTitleFromHistory({ generate: true });
     await this.touchMetadata();
     return message;
   }

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

@@ -21,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/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,6 +9,7 @@
 
 import type { LanguageModel, Tool } from "ai";
 import type { BasePlugin } from "@/plugin/core/BasePlugin.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 {
@@ -18,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 构造参数。
  */
@@ -59,10 +62,11 @@ export interface AgentOptions {
    * 当前 agent 为新建 session 提供的默认模型实例。
    *
    * 关键点（中文）
-   * - SDK 仍不负责“选择哪个模型”，这里只接收宿主已经创建好的 `LanguageModel`。
+   * - SDK 仍不负责“选择哪个模型”，这里只接收宿主已经创建好的模型实例。
+   * - 支持 AI SDK `LanguageModel`，也支持 City City 返回的 `CityModel`。
    * - 该模型会作为 session 首次执行前的默认注入值。
    */
-  model?: LanguageModel;
+  model?: AgentModel;
 
   /**
    * 当前 agent 显式持有的插件实例集合。
@@ -252,7 +256,7 @@ export interface AgentSessionSetInput {
    * - 这里接受运行中的模型实例，而不是模型 ID。
    * - 由于模型实例通常不可序列化，落盘只保留轻量可读标签用于展示。
    */
-  model?: LanguageModel;
+  model?: AgentModel;
 }
 
 /**
@@ -441,8 +445,9 @@ export interface AgentSessionSummary {
    * 当前 session 可读标题。
    *
    * 说明（中文）
-   * - 当前 SDK 不要求标题一定存在。
-   * - 若调用方需要展示列表标题，可优先使用这里；为空时再回退到 `sessionId`。
+   * - 标题持久化在 session `meta.json` 顶层。
+   * - 首条用户消息出现后，SDK 会优先生成标题，失败时回退到首条用户消息截断。
+   * - 空 session 可能暂时没有标题，调用方可回退到 `sessionId`。
    */
   title?: string;
 

package/src/types/config/AgentProject.ts

@@ -36,7 +36,7 @@ export interface AgentProjectInitializationInput {
    * 项目执行绑定配置。
    *
    * 说明（中文）
-   * - 绑定平台全局模型池中的模型 ID。
+   * - 绑定 City AIService 暴露的模型 ID。
    */
   execution: ExecutionBindingConfig;
 

package/src/types/config/DowncityConfig.ts

@@ -159,7 +159,7 @@ export interface DowncityConfig {
   id: string;
   version: string;
   /**
-   * Runtime startup configuration used by `downcity agent start`.
+   * Runtime startup configuration used by `town agent start`.
    * CLI flags (if provided) take precedence over this config.
    */
   start?: {
@@ -181,7 +181,7 @@ export interface DowncityConfig {
    *
    * 关键点（中文）
    * - 项目只有一种执行模式：`api`。
-   * - 绑定平台全局模型池中的模型 ID。
+   * - 绑定 City AIService 暴露的模型 ID。
    */
   execution?: ExecutionBindingConfig;
   /**
@@ -197,7 +197,7 @@ export interface DowncityConfig {
    *
    * 关键点（中文）
    * - `@downcity/agent` 本地 SDK 不直接消费该字段。
-   * - 宿主侧（例如 `@downcity/city`）可读取该字段控制模型工厂行为，例如 `llm.logMessages`。
+   * - 宿主侧（例如 `downcity`）可读取该字段控制模型工厂行为，例如 `llm.logMessages`。
    * - 对于项目内 `downcity.json`，通常不需要显式写 provider/model 明细。
    */
   llm?: LlmConfig;

package/src/types/config/ExecutionBinding.ts

@@ -3,7 +3,7 @@
  *
  * 关键点（中文）
  * - 项目运行入口只有一种执行模式：`api`。
- * - 绑定平台全局模型池中的模型 ID。
+ * - 绑定 City AIService 暴露的模型 ID。
  * - 该类型是项目 `downcity.json` 中唯一的执行配置。
  */
 
@@ -17,11 +17,11 @@ export interface ExecutionBindingConfig {
   type: "api";
 
   /**
-   * 平台全局模型池中的模型 ID。
+   * City AIService 中的模型 ID。
    *
    * 说明（中文）
-   * - 必须能在 `~/.downcity/downcity.db` 的模型池中解析到。
-   * - 例如：`default`、`fast`、`quality`。
+   * - 必须能通过 City 的 `/v1/ai/models` 目录查询到。
+   * - 例如：`deepseek-v4-flash`、`fast`、`quality`。
    */
   modelId: string;
 }

package/src/types/runtime/auth/AuthPermission.ts

@@ -44,8 +44,8 @@ export const AUTH_PERMISSION_DESCRIPTIONS: Record<AuthPermissionKey, string> = {
   "agent.execute": "触发 agent 执行与会话运行。",
   "task.read": "查看 task 定义与运行结果。",
   "task.run": "创建或手动执行 task。",
-  "model.read": "查看模型池与模型绑定。",
-  "model.write": "修改模型池与模型绑定。",
+  "model.read": "查看 City AIService 模型与模型绑定。",
+  "model.write": "修改模型绑定。",
   "env.read": "查看环境变量配置。",
   "env.write": "修改环境变量配置。",
   "channel.read": "查看渠道账号与渠道状态。",