@downcity/agent 1.1.11 → 1.1.12

package/src/sdk/SdkSessionSystemComposer.ts

@@ -3,19 +3,27 @@
  *
  * 关键点（中文）
  * - 面向 `Agent` SDK 的本地会话执行场景。
- * - 注入静态 PROFILE / SOUL / core prompt、显式注入 service system、显式注册 plugin system 与运行时时钟上下文。
+ * - 注入调用方显式传入的静态 instruction、显式注入 service system 与显式注册 plugin system。
+ * - SDK 不在 system 中注入动态变量；动态上下文应由调用方放入 user message。
  */
 
 import { SessionSystemComposer } from "@session/composer/system/SessionSystemComposer.js";
 import { getSessionRunScope } from "@session/SessionRunScope.js";
-import { transformPromptsIntoSystemMessages } from "@session/composer/system/default/PromptRenderer.js";
-import { buildRuntimeClockSystemPrompt } from "@session/composer/system/default/variables/VariableReplacer.js";
 import type { SessionSystemMessage } from "@/session/types/SessionPrompts.js";
+import type {
+  AgentSessionSystemBlock,
+  AgentSessionSystemSessionInfo,
+} from "@/sdk/AgentSdkTypes.js";
 
 /**
- * 解析 SDK session system messages 的输入。
+ * 解析 SDK session system blocks 的输入。
  */
-export interface ResolveSdkSessionSystemMessagesParams {
+export interface ResolveSdkSessionSystemBlocksParams {
+  /**
+   * 当前 agent 的稳定标识。
+   */
+  agentId: string;
+
   /**
    * 当前 agent 绑定的项目根目录。
    */
@@ -27,128 +35,205 @@ export interface ResolveSdkSessionSystemMessagesParams {
   sessionId: string;
 
   /**
-   * 读取当前生效的静态 system 文本集合。
+   * 当前 session 首次创建时间（ms）。
+   */
+  createdAt: number;
+
+  /**
+   * 当前 session 初始化时解析到的系统时区。
    */
-  getStaticSystemPrompts: () => string[];
+  timezone: string;
 
   /**
-   * 读取当前显式注入 service 的 system 文本集合。
+   * 读取当前 SDK 调用方传入的 instruction system blocks。
    */
-  getServiceSystemPrompts: () => Promise<string[]>;
+  getInstructionSystemBlocks: () => AgentSessionSystemBlock[];
 
   /**
-   * 读取当前显式注册 plugin 的 system 文本集合。
+   * 读取当前显式注入 service 的 system blocks。
    */
-  getPluginSystemPrompts: () => Promise<string[]>;
+  getServiceSystemBlocks: () => Promise<AgentSessionSystemBlock[]>;
+
+  /**
+   * 读取当前显式注册 plugin 的 system blocks。
+   */
+  getPluginSystemBlocks: () => Promise<AgentSessionSystemBlock[]>;
 }
 
 type SdkSessionSystemComposerOptions = {
   /**
-   * 当前 agent 绑定的项目根目录。
+   * 当前 agent 的稳定标识。
    */
-  projectRoot: string;
+  agentId: string;
 
   /**
-   * 读取当前生效的静态 system 文本集合。
+   * 当前 agent 绑定的项目根目录。
    */
-  getStaticSystemPrompts: () => string[];
+  projectRoot: string;
 
   /**
-   * 读取当前显式注册 plugin 的 system 文本集合。
+   * 读取当前 session 首次创建时间（ms）。
    */
-  getPluginSystemPrompts: () => Promise<string[]>;
+  getSessionCreatedAt: () => number;
 
   /**
-   * 读取当前显式注入 service 的 system 文本集合。
+   * 读取当前 session 初始化时解析到的系统时区。
    */
-  getServiceSystemPrompts: () => Promise<string[]>;
-};
+  getSessionTimezone: () => string;
 
-async function resolvePromptMessages(params: {
   /**
-   * 原始 system prompt 文本集合。
+   * 读取当前 SDK 调用方传入的 instruction system blocks。
    */
-  prompts: string[];
+  getInstructionSystemBlocks: () => AgentSessionSystemBlock[];
+
   /**
-   * 当前项目根目录。
+   * 读取当前显式注册 plugin 的 system blocks。
    */
-  projectRoot: string;
+  getPluginSystemBlocks: () => Promise<AgentSessionSystemBlock[]>;
+
   /**
-   * 当前 sessionId。
+   * 读取当前显式注入 service 的 system blocks。
    */
-  sessionId: string;
-}): Promise<SessionSystemMessage[]> {
-  const nonEmptyPrompts = params.prompts.filter((item) =>
-    String(item || "").trim(),
-  );
-  return await transformPromptsIntoSystemMessages(nonEmptyPrompts, {
-    projectPath: params.projectRoot,
-    sessionId: params.sessionId,
-    variableMode: "stable",
-  });
+  getServiceSystemBlocks: () => Promise<AgentSessionSystemBlock[]>;
+};
+
+function normalizeSystemBlocks(
+  blocks: AgentSessionSystemBlock[],
+): AgentSessionSystemBlock[] {
+  if (!Array.isArray(blocks)) return [];
+  return blocks
+    .map((block) => {
+      const content = String(block?.content || "").trim();
+      if (!content) return null;
+      const source = block.source;
+      if (
+        source !== "core" &&
+        source !== "instruction" &&
+        source !== "service" &&
+        source !== "plugin" &&
+        source !== "session"
+      ) {
+        return null;
+      }
+      return {
+        source,
+        name: String(block.name || source).trim() || source,
+        content,
+      } satisfies AgentSessionSystemBlock;
+    })
+    .filter((block): block is AgentSessionSystemBlock => Boolean(block));
+}
+
+function createSessionInfo(
+  params: Pick<
+    ResolveSdkSessionSystemBlocksParams,
+    "agentId" | "sessionId" | "projectRoot" | "createdAt" | "timezone"
+  >,
+): AgentSessionSystemSessionInfo {
+  const createdAt = Number.isFinite(params.createdAt) ? params.createdAt : 0;
+  return {
+    agentId: String(params.agentId || "").trim(),
+    sessionId: String(params.sessionId || "").trim(),
+    projectRoot: String(params.projectRoot || "").trim(),
+    createdAt: new Date(createdAt).toISOString(),
+    timezone: String(params.timezone || "").trim() || "UTC",
+  };
+}
+
+function createSessionSystemBlock(
+  session: AgentSessionSystemSessionInfo,
+): AgentSessionSystemBlock {
+  const content = [
+    "当前会话上下文：",
+    `你正在服务 agent "${session.agentId}" 的 session "${session.sessionId}"。`,
+    `当前项目根目录是 "${session.projectRoot}"。`,
+    `本会话创建于 ${session.createdAt}，参考时区是 ${session.timezone}。`,
+    "这个创建时间是当前会话的稳定参考时间，不代表每轮运行时的当前时间。",
+    "如果用户消息中提供了新的当前时间、相对时间或其他动态上下文，应优先使用用户消息中的动态信息。",
+  ].join("\n");
+  return {
+    source: "session",
+    name: "context",
+    content,
+  };
 }
 
 /**
- * 解析 SDK session 当前生效的 system messages。
+ * 解析 SDK session 当前生效的 system blocks。
  */
-export async function resolveSdkSessionSystemMessages(
-  params: ResolveSdkSessionSystemMessagesParams,
-): Promise<SessionSystemMessage[]> {
+export async function resolveSdkSessionSystemBlocks(
+  params: ResolveSdkSessionSystemBlocksParams,
+): Promise<AgentSessionSystemBlock[]> {
+  const agentId = String(params.agentId || "").trim();
   const projectRoot = String(params.projectRoot || "").trim();
   const sessionId = String(params.sessionId || "").trim();
+  const createdAt = Number(params.createdAt || 0);
+  const timezone = String(params.timezone || "").trim();
+  if (!agentId) {
+    throw new Error("resolveSdkSessionSystemBlocks requires a non-empty agentId");
+  }
   if (!projectRoot) {
-    throw new Error("resolveSdkSessionSystemMessages requires a non-empty projectRoot");
+    throw new Error("resolveSdkSessionSystemBlocks requires a non-empty projectRoot");
   }
   if (!sessionId) {
-    throw new Error("resolveSdkSessionSystemMessages requires a non-empty sessionId");
+    throw new Error("resolveSdkSessionSystemBlocks requires a non-empty sessionId");
+  }
+  if (!Number.isFinite(createdAt) || createdAt <= 0) {
+    throw new Error("resolveSdkSessionSystemBlocks requires a valid createdAt");
+  }
+  if (!timezone) {
+    throw new Error("resolveSdkSessionSystemBlocks requires a non-empty timezone");
   }
-  const staticMessages = await resolvePromptMessages({
-    prompts: params.getStaticSystemPrompts(),
-    projectRoot,
-    sessionId,
-  });
-  const serviceMessages = await resolvePromptMessages({
-    prompts: await params.getServiceSystemPrompts(),
-    projectRoot,
-    sessionId,
-  });
-  const pluginMessages = await resolvePromptMessages({
-    prompts: await params.getPluginSystemPrompts(),
-    projectRoot,
-    sessionId,
-  });
-
   return [
-    ...staticMessages,
-    ...serviceMessages,
-    ...pluginMessages,
-    {
-      role: "system" as const,
-      content: buildRuntimeClockSystemPrompt({
-        projectPath: projectRoot,
-        sessionId,
-      }),
-    },
+    ...normalizeSystemBlocks(params.getInstructionSystemBlocks()),
+    ...normalizeSystemBlocks(await params.getServiceSystemBlocks()),
+    ...normalizeSystemBlocks(await params.getPluginSystemBlocks()),
+    // session block 放在最后，尽量保留前缀 system blocks 的跨 session 缓存命中。
+    createSessionSystemBlock(
+      createSessionInfo({ agentId, projectRoot, sessionId, createdAt, timezone }),
+    ),
   ];
 }
 
+/**
+ * 解析 SDK session 当前生效的 system messages。
+ */
+export async function resolveSdkSessionSystemMessages(
+  params: ResolveSdkSessionSystemBlocksParams,
+): Promise<SessionSystemMessage[]> {
+  const blocks = await resolveSdkSessionSystemBlocks(params);
+  return blocks.map((block) => ({
+    role: "system" as const,
+    content: block.content,
+  }));
+}
+
 /**
  * SDK Session system composer 实现。
  */
 export class SdkSessionSystemComposer extends SessionSystemComposer {
   readonly name = "sdk_prompt_system";
 
+  private readonly agentId: string;
   private readonly projectRoot: string;
-  private readonly getStaticSystemPrompts: SdkSessionSystemComposerOptions["getStaticSystemPrompts"];
-  private readonly getServiceSystemPrompts: SdkSessionSystemComposerOptions["getServiceSystemPrompts"];
-  private readonly getPluginSystemPrompts: SdkSessionSystemComposerOptions["getPluginSystemPrompts"];
+  private readonly getSessionCreatedAt: SdkSessionSystemComposerOptions["getSessionCreatedAt"];
+  private readonly getSessionTimezone: SdkSessionSystemComposerOptions["getSessionTimezone"];
+  private readonly getInstructionSystemBlocks: SdkSessionSystemComposerOptions["getInstructionSystemBlocks"];
+  private readonly getServiceSystemBlocks: SdkSessionSystemComposerOptions["getServiceSystemBlocks"];
+  private readonly getPluginSystemBlocks: SdkSessionSystemComposerOptions["getPluginSystemBlocks"];
 
   constructor(options: SdkSessionSystemComposerOptions) {
     super();
+    this.agentId = String(options.agentId || "").trim();
     this.projectRoot = String(options.projectRoot || "").trim();
-    this.getStaticSystemPrompts = options.getStaticSystemPrompts;
-    this.getServiceSystemPrompts = options.getServiceSystemPrompts;
-    this.getPluginSystemPrompts = options.getPluginSystemPrompts;
+    this.getSessionCreatedAt = options.getSessionCreatedAt;
+    this.getSessionTimezone = options.getSessionTimezone;
+    this.getInstructionSystemBlocks = options.getInstructionSystemBlocks;
+    this.getServiceSystemBlocks = options.getServiceSystemBlocks;
+    this.getPluginSystemBlocks = options.getPluginSystemBlocks;
+    if (!this.agentId) {
+      throw new Error("SdkSessionSystemComposer requires a non-empty agentId");
+    }
     if (!this.projectRoot) {
       throw new Error("SdkSessionSystemComposer requires a non-empty projectRoot");
     }
@@ -163,11 +248,14 @@ export class SdkSessionSystemComposer extends SessionSystemComposer {
       throw new Error("SdkSessionSystemComposer.resolve requires a non-empty sessionId");
     }
     return await resolveSdkSessionSystemMessages({
+      agentId: this.agentId,
       projectRoot: this.projectRoot,
       sessionId,
-      getStaticSystemPrompts: this.getStaticSystemPrompts,
-      getServiceSystemPrompts: this.getServiceSystemPrompts,
-      getPluginSystemPrompts: this.getPluginSystemPrompts,
+      createdAt: this.getSessionCreatedAt(),
+      timezone: this.getSessionTimezone(),
+      getInstructionSystemBlocks: this.getInstructionSystemBlocks,
+      getServiceSystemBlocks: this.getServiceSystemBlocks,
+      getPluginSystemBlocks: this.getPluginSystemBlocks,
     });
   }
 }

package/src/sdk/Session.ts

@@ -22,14 +22,19 @@ import type {
   AgentSessionRunResult,
   AgentSessionSetInput,
   AgentSessionStreamEvent,
+  AgentSessionSystemBlock,
+  AgentSessionSystemSnapshot,
 } from "@/sdk/AgentSdkTypes.js";
 import type { SessionMessageV1 } from "@/session/types/SessionMessages.js";
-import { SdkSessionSystemComposer } from "@/sdk/SdkSessionSystemComposer.js";
-import { resolveSdkSessionSystemMessages } from "@/sdk/SdkSessionSystemComposer.js";
+import {
+  resolveSdkSessionSystemBlocks,
+  SdkSessionSystemComposer,
+} from "@/sdk/SdkSessionSystemComposer.js";
 import {
   inferModelLabel,
   patchSdkSessionModelLabel,
   readSdkSessionMetadata,
+  resolveSystemTimezone,
   writeSdkSessionMetadata,
 } from "@/sdk/SessionMetadata.js";
 import {
@@ -75,19 +80,19 @@ type SdkSessionOptions = {
   };
 
   /**
-   * 读取静态 system 文本集合。
+   * 读取当前 SDK 调用方传入的 instruction system blocks。
    */
-  getStaticSystemPrompts: () => string[];
+  getInstructionSystemBlocks: () => AgentSessionSystemBlock[];
 
   /**
-   * 读取当前 agent 显式注入 service 的 system 文本集合。
+   * 读取当前 agent 显式注入 service 的 system blocks。
    */
-  getServiceSystemPrompts: () => Promise<string[]>;
+  getServiceSystemBlocks: () => Promise<AgentSessionSystemBlock[]>;
 
   /**
-   * 读取当前 agent 显式注册 plugin 的 system 文本集合。
+   * 读取当前 agent 显式注册 plugin 的 system blocks。
    */
-  getPluginSystemPrompts: () => Promise<string[]>;
+  getPluginSystemBlocks: () => Promise<AgentSessionSystemBlock[]>;
 };
 
 /**
@@ -100,12 +105,14 @@ export class SdkSession {
   private readonly projectRoot: string;
   private readonly tools: Record<string, Tool>;
   private readonly logger: SdkSessionOptions["logger"];
-  private readonly getStaticSystemPrompts: SdkSessionOptions["getStaticSystemPrompts"];
-  private readonly getServiceSystemPrompts: SdkSessionOptions["getServiceSystemPrompts"];
-  private readonly getPluginSystemPrompts: SdkSessionOptions["getPluginSystemPrompts"];
+  private readonly getInstructionSystemBlocks: SdkSessionOptions["getInstructionSystemBlocks"];
+  private readonly getServiceSystemBlocks: SdkSessionOptions["getServiceSystemBlocks"];
+  private readonly getPluginSystemBlocks: SdkSessionOptions["getPluginSystemBlocks"];
   private readonly historyComposer: JsonlSessionHistoryComposer;
   private readonly coreSession: CoreSession;
   private sessionConfig: AgentSessionConfigSnapshot = {};
+  private createdAt = Date.now();
+  private timezone = resolveSystemTimezone();
   private initializePromise: Promise<this> | null = null;
   private servicePort: SessionPort | null = null;
 
@@ -115,9 +122,9 @@ export class SdkSession {
     this.projectRoot = String(options.projectRoot || "").trim();
     this.tools = options.tools;
     this.logger = options.logger;
-    this.getStaticSystemPrompts = options.getStaticSystemPrompts;
-    this.getServiceSystemPrompts = options.getServiceSystemPrompts;
-    this.getPluginSystemPrompts = options.getPluginSystemPrompts;
+    this.getInstructionSystemBlocks = options.getInstructionSystemBlocks;
+    this.getServiceSystemBlocks = options.getServiceSystemBlocks;
+    this.getPluginSystemBlocks = options.getPluginSystemBlocks;
     if (!this.id) {
       throw new Error("SdkSession requires a non-empty sessionId");
     }
@@ -166,10 +173,13 @@ export class SdkSession {
           historyComposer,
           compactionComposer: new JsonlSessionCompactionComposer(),
           systemComposer: new SdkSessionSystemComposer({
+            agentId: this.agentId,
             projectRoot: this.projectRoot,
-            getStaticSystemPrompts: this.getStaticSystemPrompts,
-            getServiceSystemPrompts: this.getServiceSystemPrompts,
-            getPluginSystemPrompts: this.getPluginSystemPrompts,
+            getSessionCreatedAt: () => this.createdAt,
+            getSessionTimezone: () => this.timezone,
+            getInstructionSystemBlocks: this.getInstructionSystemBlocks,
+            getServiceSystemBlocks: this.getServiceSystemBlocks,
+            getPluginSystemBlocks: this.getPluginSystemBlocks,
           }),
           getTools: () => this.tools,
         });
@@ -190,6 +200,12 @@ export class SdkSession {
         agentId: this.agentId,
         sessionId: this.id,
       });
+      const createdAt =
+        typeof metadata.createdAt === "number" ? metadata.createdAt : Date.now();
+      const timezone =
+        typeof metadata.timezone === "string" && metadata.timezone.trim()
+          ? metadata.timezone.trim()
+          : resolveSystemTimezone();
       await writeSdkSessionMetadata({
         projectRoot: this.projectRoot,
         agentId: this.agentId,
@@ -197,10 +213,12 @@ export class SdkSession {
         meta: {
           ...metadata,
           agentId: this.agentId,
-          createdAt:
-            typeof metadata.createdAt === "number" ? metadata.createdAt : Date.now(),
+          createdAt,
+          timezone,
         },
       });
+      this.createdAt = createdAt;
+      this.timezone = timezone;
       this.sessionConfig = {
         ...(metadata.sdkConfig?.modelLabel
           ? { modelLabel: metadata.sdkConfig.modelLabel }
@@ -279,20 +297,31 @@ export class SdkSession {
    *
    * 关键点（中文）
    * - 返回内容与实际 run 时使用的 SDK system composer 同源。
-   * - 包含静态 system、显式注入 service system、显式注册 plugin system 与 runtime clock。
-   * - 这里只返回文本数组，不把 system prompt 写入会话历史。
+   * - 包含 instruction/core、显式注入 service system、显式注册 plugin system 与 session 上下文。
+   * - 返回结构化快照，不把 system prompt 写入会话历史。
    */
-  async system(): Promise<string[]> {
-    const messages = await resolveSdkSessionSystemMessages({
+  async system(): Promise<AgentSessionSystemSnapshot> {
+    const blocks = await resolveSdkSessionSystemBlocks({
+      agentId: this.agentId,
       projectRoot: this.projectRoot,
       sessionId: this.id,
-      getStaticSystemPrompts: this.getStaticSystemPrompts,
-      getServiceSystemPrompts: this.getServiceSystemPrompts,
-      getPluginSystemPrompts: this.getPluginSystemPrompts,
+      createdAt: this.createdAt,
+      timezone: this.timezone,
+      getInstructionSystemBlocks: this.getInstructionSystemBlocks,
+      getServiceSystemBlocks: this.getServiceSystemBlocks,
+      getPluginSystemBlocks: this.getPluginSystemBlocks,
     });
-    return messages
-      .map((message) => String(message.content || ""))
-      .filter((content) => content.trim().length > 0);
+    return {
+      sessionId: this.id,
+      session: {
+        agentId: this.agentId,
+        sessionId: this.id,
+        projectRoot: this.projectRoot,
+        createdAt: new Date(this.createdAt).toISOString(),
+        timezone: this.timezone,
+      },
+      blocks,
+    };
   }
 
   /**
@@ -401,9 +430,9 @@ export class SdkSession {
       sessionId: `fork-${Date.now()}-${nanoid(8)}`,
       tools: this.tools,
       logger: this.logger,
-      getStaticSystemPrompts: this.getStaticSystemPrompts,
-      getServiceSystemPrompts: this.getServiceSystemPrompts,
-      getPluginSystemPrompts: this.getPluginSystemPrompts,
+      getInstructionSystemBlocks: this.getInstructionSystemBlocks,
+      getServiceSystemBlocks: this.getServiceSystemBlocks,
+      getPluginSystemBlocks: this.getPluginSystemBlocks,
     });
     await forked.initialize();
     if (this.sessionConfig.model) {

package/src/sdk/SessionMetadata.ts

@@ -36,6 +36,21 @@ function normalizeModelLabel(input: unknown): string | undefined {
   return label || undefined;
 }
 
+/**
+ * 读取当前系统时区。
+ */
+export function resolveSystemTimezone(): string {
+  const timezone = Intl.DateTimeFormat().resolvedOptions().timeZone;
+  return typeof timezone === "string" && timezone.trim()
+    ? timezone.trim()
+    : "UTC";
+}
+
+function normalizeTimezone(input: unknown): string | undefined {
+  const timezone = typeof input === "string" ? input.trim() : "";
+  return timezone || undefined;
+}
+
 /**
  * 从模型实例推导轻量可读标签。
  */
@@ -83,6 +98,7 @@ export async function readSdkSessionMetadata(
         typeof raw.createdAt === "number" && Number.isFinite(raw.createdAt)
           ? raw.createdAt
           : Date.now(),
+      timezone: normalizeTimezone(raw.timezone) || resolveSystemTimezone(),
       updatedAt:
         typeof raw.updatedAt === "number" && Number.isFinite(raw.updatedAt)
           ? raw.updatedAt
@@ -116,6 +132,7 @@ export async function readSdkSessionMetadata(
       sessionId: input.sessionId,
       agentId: input.agentId,
       createdAt: Date.now(),
+      timezone: resolveSystemTimezone(),
       updatedAt: 0,
       pinnedSkillIds: [],
     };
@@ -160,6 +177,7 @@ export async function patchSdkSessionModelLabel(
     agentId: input.agentId,
     createdAt:
       typeof current.createdAt === "number" ? current.createdAt : Date.now(),
+    timezone: normalizeTimezone(current.timezone) || resolveSystemTimezone(),
     updatedAt: Date.now(),
     ...(modelLabel
       ? {

package/src/session/types/SessionHistoryMeta.ts

@@ -27,6 +27,8 @@ export type SessionHistoryMetaV1 = {
   agentId?: string;
   /** 当前 session 首次创建时间戳（ms）。 */
   createdAt?: number;
+  /** 当前 session 初始化时解析到的系统时区。 */
+  timezone?: string;
   /** 最近一次更新元信息的时间戳（ms）。 */
   updatedAt: number;
   /** 固定注入到 Session 上下文的 skill id 列表。 */