@downcity/agent 1.1.11 → 1.1.13

package/bin/session/types/SessionLoop.js

@@ -1,5 +1,5 @@
 /**
- * LocalSessionCore tool-loop 决策相关类型。
+ * Runner tool-loop 决策相关类型。
  *
  * 关键点（中文）
  * - 这里只描述“是否继续下一轮”的纯决策输入/输出。

package/bin/session/types/SessionRun.d.ts

@@ -3,7 +3,7 @@
  *
  * 关键点（中文）
  * - `SessionRunInput` 表示上层会话入口输入（例如 context query）。
- * - `SessionExecuteInput` 表示 LocalSessionCore 通过 Composer 装配后的中间运行态。
+ * - `SessionExecuteInput` 表示 Runner 通过 Composer 装配后的中间运行态。
  * - 输出仅暴露 assistantMessage（UIMessage）。
  */
 import type { Tool, UIMessageChunk } from "ai";
@@ -89,7 +89,7 @@ export interface SessionRunInput {
     query: string;
 }
 /**
- * LocalSessionCore 通过 Composer 装配后的中间运行态。
+ * Runner 通过 Composer 装配后的中间运行态。
  */
 export interface SessionExecuteInput {
     /**

package/bin/session/types/SessionRun.js

@@ -3,7 +3,7 @@
  *
  * 关键点（中文）
  * - `SessionRunInput` 表示上层会话入口输入（例如 context query）。
- * - `SessionExecuteInput` 表示 LocalSessionCore 通过 Composer 装配后的中间运行态。
+ * - `SessionExecuteInput` 表示 Runner 通过 Composer 装配后的中间运行态。
  * - 输出仅暴露 assistantMessage（UIMessage）。
  */
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@downcity/agent",
-  "version": "1.1.11",
+  "version": "1.1.13",
   "type": "module",
   "description": "Downcity Agent 运行时 — 执行壳，通过 RPC/HTTP 调用 City 的能力",
   "main": "./bin/index.js",

package/src/index.ts

@@ -9,6 +9,7 @@
 
 // SDK 入口
 export { Agent } from "./sdk/Agent.js";
+export { Session } from "./sdk/Session.js";
 export { RemoteAgent } from "./sdk/RemoteAgent.js";
 export type {
   AgentOptions,
@@ -20,6 +21,10 @@ export type {
   AgentSessionRunResult,
   AgentSessionSetInput,
   AgentSessionStreamEvent,
+  AgentSessionSystemBlock,
+  AgentSessionSystemBlockSource,
+  AgentSessionSystemSessionInfo,
+  AgentSessionSystemSnapshot,
 } from "./sdk/AgentSdkTypes.js";
 
 // 服务与插件作者 API
@@ -57,7 +62,7 @@ export type { AgentRuntime, AgentRuntimeBase } from "./runtime/AgentRuntimeState
 export type { AgentContext } from "./runtime/AgentContextTypes.js";
 
 // Session 与即时执行集成
-export { Session } from "./session/Session.js";
+export { Executor } from "./session/Executor.js";
 export {
   drainDeferredPersistedUserMessages,
   getSessionRunScope,
@@ -67,7 +72,6 @@ export { JsonlSessionCompactionComposer } from "./session/composer/compaction/js
 export { SessionSystemComposer } from "./session/composer/system/SessionSystemComposer.js";
 export { transformPromptsIntoSystemMessages } from "./session/composer/system/default/PromptRenderer.js";
 export { loadStaticSystemPrompts } from "./session/composer/system/default/StaticPromptCatalog.js";
-export { LocalSessionExecutor } from "./session/executors/local/LocalSessionExecutor.js";
 
 // Agent server 与 transport 集成
 export { startServer } from "./server/http/Server.js";

package/src/runtime/AgentRuntime.ts

@@ -5,13 +5,12 @@
  * - 这里是单 agent 宿主的主装配入口，负责把 config、model、session、service、plugin 串起来。
  * - 完整运行态类型仍由 `AgentRuntimeState.ts` 维护；本模块只负责装配与对外导出。
  * - 该模块同时负责热重载提示词系统与导出统一的 `getAgentContext()` 入口。
- * - 当前只有 `api` 执行模式：从 console 模型池取模型，走 LocalSessionCore。
+ * - 当前只有 `api` 执行模式：从 console 模型池取模型，走 Runner。
  */
 
 import path from "path";
 import fs from "fs";
 import { logger as defaultLogger } from "@/utils/logger/Logger.js";
-import { LocalSessionExecutor } from "@session/executors/local/LocalSessionExecutor.js";
 import { ensureRuntimeProjectReady } from "@/host/daemon/ProjectSetup.js";
 import { createModel } from "@/model/CreateModel.js";
 import {
@@ -29,7 +28,6 @@ import { getSessionRunScope } from "@session/SessionRunScope.js";
 import { JsonlSessionHistoryComposer } from "@session/composer/history/jsonl/JsonlSessionHistoryComposer.js";
 import { JsonlSessionCompactionComposer } from "@session/composer/compaction/jsonl/JsonlSessionCompactionComposer.js";
 import { DefaultSessionSystemComposer } from "@session/composer/system/default/DefaultSessionSystemComposer.js";
-import type { SessionHistoryComposer } from "@session/composer/history/SessionHistoryComposer.js";
 import { ChatSession } from "@/service/builtins/chat/runtime/ChatSession.js";
 import { ChatSessionExecutionComposer } from "@/service/builtins/chat/runtime/ChatSessionExecutionComposer.js";
 import {
@@ -224,7 +222,7 @@ function createSessionHistoryComposer(
  * 初始化入口。
  *
  * 关键点（中文）
- * - 只有 api 执行模式：从 console 模型池创建模型 → LocalSessionExecutor → LocalSessionCore。
+ * - 只有 api 执行模式：从 console 模型池创建模型 → Executor → Runner。
  */
 export async function initAgentRuntime(
   cwd: string,
@@ -326,19 +324,11 @@ export async function initAgentRuntime(
       sessionId: key,
       historyComposer,
       executionComposer,
-      createExecutor: (
-        sessionHistoryComposer: SessionHistoryComposer,
-        chatExecutionComposer: ChatSessionExecutionComposer,
-      ) =>
-        new LocalSessionExecutor({
-          model,
-          logger: defaultLogger,
-          historyComposer: sessionHistoryComposer,
-          compactionComposer,
-          systemComposer,
-          getTools: () => shellTools,
-          executionComposer: chatExecutionComposer,
-        }),
+      getModel: () => model,
+      logger: defaultLogger,
+      compactionComposer,
+      systemComposer,
+      getTools: () => shellTools,
     });
     sessionsById.set(key, created);
     return created;

package/src/runtime/AgentRuntimeTypes.ts

@@ -16,7 +16,7 @@ import type {
   AgentPluginConfigRuntime,
 } from "@/types/host/AgentHost.js";
 import type { BaseService } from "@/service/builtins/BaseService.js";
-import type { Session } from "@session/Session.js";
+import type { Executor } from "@session/Executor.js";
 
 /**
  * AgentRuntime 启动早期的基础状态。
@@ -73,9 +73,9 @@ export interface AgentRuntime extends AgentRuntimeBase {
    */
   model?: LanguageModel;
   /**
-   * 读取指定 sessionId 对应的 Session 实例。
+   * 读取指定 sessionId 对应的内部 Executor 实例。
    */
-  getSession(sessionId: string): Session;
+  getSession(sessionId: string): Executor;
   /**
    * 返回当前执行中的 sessionId 列表。
    */

package/src/sdk/Agent.ts

@@ -2,7 +2,7 @@
  * Agent SDK 本地入口。
  *
  * 关键点（中文）
- * - `new Agent({ id, path, tools, services, plugins })` 只做同步装配，不在构造阶段启动任何 I/O。
+ * - `new Agent({ id, path, instruction, tools, services, plugins })` 只做同步装配，不在构造阶段启动任何 I/O。
  * - session、HTTP、RPC、service lifecycle 都按需异步初始化。
  * - SDK Agent 通过最小 `AgentContext` 适配层复用现有 service/plugin/chat 运行协议，而不是重复实现一套执行链。
  */
@@ -26,9 +26,10 @@ import type {
 import type {
   AgentOptions,
   AgentSessionMetadata,
+  AgentSessionSystemBlock,
 } from "@/sdk/AgentSdkTypes.js";
-import { SdkSession } from "@/sdk/Session.js";
-import { loadStaticSystemPrompts } from "@session/composer/system/default/StaticPromptCatalog.js";
+import { Session } from "@/sdk/Session.js";
+import { DEFAULT_SHIP_PROMPTS } from "@session/composer/system/default/SystemDomain.js";
 import { getSdkAgentSessionsRootDirPath } from "@/sdk/Paths.js";
 import { SdkAgentHttpServer } from "@/sdk/HttpServer.js";
 import { SdkAgentRpcServer } from "@/sdk/RpcServer.js";
@@ -70,6 +71,41 @@ function createFallbackSdkConfig(agentId: string): DowncityConfig {
   } as DowncityConfig;
 }
 
+function normalizeInstructionInput(input: string | string[] | undefined): string[] {
+  const items = Array.isArray(input) ? input : typeof input === "string" ? [input] : [];
+  return items
+    .map((item) => String(item || "").trim())
+    .filter((item) => item.length > 0);
+}
+
+function createCoreInstructionContent(projectRoot: string): string {
+  const currentYear = String(new Date().getFullYear());
+  return DEFAULT_SHIP_PROMPTS
+    .replaceAll("{{project_path}}", projectRoot)
+    .replaceAll("{{project_root}}", projectRoot)
+    .replaceAll("{{current_year}}", currentYear);
+}
+
+function createInstructionSystemBlocks(
+  instruction: string[],
+  projectRoot: string,
+): AgentSessionSystemBlock[] {
+  if (instruction.length === 0) {
+    return [
+      {
+        source: "core",
+        name: "default",
+        content: createCoreInstructionContent(projectRoot),
+      },
+    ];
+  }
+  return instruction.map((content, index) => ({
+    source: "instruction" as const,
+    name: instruction.length === 1 ? "agent" : `agent:${index + 1}`,
+    content,
+  }));
+}
+
 /**
  * SDK 本地 Agent。
  */
@@ -83,14 +119,14 @@ export class Agent {
   readonly plugins: PluginPort;
 
   private readonly logger: Logger;
-  private readonly sessionsById = new Map<string, SdkSession>();
+  private readonly sessionsById = new Map<string, Session>();
   private readonly runtime: AgentRuntime;
   private readonly serviceContext: AgentContext;
   private readonly pluginRegistry: PluginRegistry;
   private readonly pluginSystemProviders: Plugin[];
   private readonly config: DowncityConfig;
   private readonly platform: AgentPlatformRuntime;
-  private systems: string[];
+  private instruction: string[];
   private servicesStartPromise: Promise<void> | null = null;
 
   constructor(options: AgentOptions) {
@@ -109,7 +145,7 @@ export class Agent {
     this.logger = new Logger();
     this.logger.bindProjectRoot(this.path);
     this.platform = options.platform || EMPTY_SDK_PLATFORM;
-    this.systems = loadStaticSystemPrompts(this.path);
+    this.instruction = normalizeInstructionInput(options.instruction);
     this.config = this.loadConfig();
     this.services = this.createServiceMap(options.services || []);
     this.runtime = this.createRuntime();
@@ -129,7 +165,7 @@ export class Agent {
   /**
    * 获取或创建一个 session。
    */
-  async session(sessionId?: string): Promise<SdkSession> {
+  async session(sessionId?: string): Promise<Session> {
     const session = this.getOrCreateSession(sessionId);
     await session.initialize();
     return session;
@@ -176,10 +212,14 @@ export class Agent {
   }
 
   /**
-   * 刷新静态 system 文本集合。
+   * 更新当前 SDK Agent 的静态基础指令。
+   *
+   * 关键点（中文）
+   * - instruction 不做动态变量替换。
+   * - 已创建的 session 后续 run 会读取最新 instruction blocks。
    */
-  reloadStaticPrompts(): void {
-    this.systems = loadStaticSystemPrompts(this.path);
+  setInstruction(input: string | string[]): void {
+    this.instruction = normalizeInstructionInput(input);
   }
 
   private loadConfig(): DowncityConfig {
@@ -252,8 +292,12 @@ export class Agent {
     };
   }
 
-  private async loadPluginSystemPrompts(): Promise<string[]> {
-    const out: string[] = [];
+  private loadInstructionSystemBlocks(): AgentSessionSystemBlock[] {
+    return createInstructionSystemBlocks(this.instruction, this.path);
+  }
+
+  private async loadPluginSystemBlocks(): Promise<AgentSessionSystemBlock[]> {
+    const out: AgentSessionSystemBlock[] = [];
     for (const plugin of this.pluginSystemProviders) {
       if (typeof plugin.system !== "function") continue;
       try {
@@ -264,7 +308,11 @@ export class Agent {
         }
         const text = String(await plugin.system(this.serviceContext)).trim();
         if (!text) continue;
-        out.push(text);
+        out.push({
+          source: "plugin",
+          name: plugin.name,
+          content: text,
+        });
       } catch {
         // 单个 plugin system 失败不应阻断 SDK session 主链路。
       }
@@ -272,14 +320,18 @@ export class Agent {
     return out;
   }
 
-  private async loadServiceSystemPrompts(): Promise<string[]> {
-    const out: string[] = [];
+  private async loadServiceSystemBlocks(): Promise<AgentSessionSystemBlock[]> {
+    const out: AgentSessionSystemBlock[] = [];
     for (const service of this.services.values()) {
       if (typeof service.system !== "function") continue;
       try {
         const text = String(await service.system(this.serviceContext)).trim();
         if (!text) continue;
-        out.push(text);
+        out.push({
+          source: "service",
+          name: service.name,
+          content: text,
+        });
       } catch {
         // 单个 service system 失败不应阻断 SDK session 主链路。
       }
@@ -295,7 +347,7 @@ export class Agent {
       config: this.config,
       env: {},
       globalEnv: {},
-      systems: this.systems,
+      systems: this.instruction,
       paths: createAgentPathRuntime(this.path),
       pluginConfig: createAgentPluginConfigRuntime(this.path),
       platform: this.platform,
@@ -326,7 +378,7 @@ export class Agent {
       config: this.config,
       env: {},
       globalEnv: {},
-      systems: this.systems,
+      systems: this.instruction,
       paths: this.runtime.paths,
       pluginConfig: this.runtime.pluginConfig,
       platform: this.platform,
@@ -397,21 +449,21 @@ export class Agent {
     return context;
   }
 
-  private getOrCreateSession(sessionId?: string): SdkSession {
+  private getOrCreateSession(sessionId?: string): Session {
     const resolvedSessionId =
       String(sessionId || "").trim() || `session-${Date.now()}-${nanoid(8)}`;
     const cached = this.sessionsById.get(resolvedSessionId);
     if (cached) return cached;
 
-    const created = new SdkSession({
+    const created = new Session({
       agentId: this.id,
       projectRoot: this.path,
       sessionId: resolvedSessionId,
       tools: this.tools,
       logger: this.logger,
-      getStaticSystemPrompts: () => this.systems,
-      getServiceSystemPrompts: () => this.loadServiceSystemPrompts(),
-      getPluginSystemPrompts: () => this.loadPluginSystemPrompts(),
+      getInstructionSystemBlocks: () => this.loadInstructionSystemBlocks(),
+      getServiceSystemBlocks: () => this.loadServiceSystemBlocks(),
+      getPluginSystemBlocks: () => this.loadPluginSystemBlocks(),
     });
     this.sessionsById.set(resolvedSessionId, created);
     return created;

package/src/sdk/AgentSdkTypes.ts

@@ -41,6 +41,16 @@ export interface AgentOptions {
    */
   tools?: Record<string, Tool>;
 
+  /**
+   * 调用方显式传入的静态基础指令。
+   *
+   * 关键点（中文）
+   * - `instruction` 是稳定、缓存友好的 system 前缀，不做动态变量替换。
+   * - SDK 不主动读取 `PROFILE.md` / `SOUL.md`；这类项目文件应由 city 或调用方读取后传入。
+   * - 未传入时，SDK 会使用包内最小 core instruction 作为 fallback。
+   */
+  instruction?: string | string[];
+
   /**
    * 当前 agent 显式持有的 service 实例集合。
    *
@@ -246,6 +256,109 @@ export type AgentSessionStreamEvent =
       error: string;
     };
 
+/**
+ * Session system block 来源类型。
+ */
+export type AgentSessionSystemBlockSource =
+  | "core"
+  | "instruction"
+  | "service"
+  | "plugin"
+  | "session";
+
+/**
+ * Session system prompt 的单个组成块。
+ */
+export interface AgentSessionSystemBlock {
+  /**
+   * 当前 block 的来源层级。
+   */
+  source: AgentSessionSystemBlockSource;
+
+  /**
+   * 当前 block 在来源层级内的名称。
+   *
+   * 说明（中文）
+   * - `instruction` 通常使用 `agent`。
+   * - `service` / `plugin` 使用对应 service/plugin 名称。
+   * - `core` 使用 `default`。
+   * - `session` 使用当前 session 上下文名称。
+   */
+  name: string;
+
+  /**
+   * 已归一化后的 system 文本内容。
+   *
+   * 关键点（中文）
+   * - SDK 不对 instruction 做动态变量替换。
+   * - 动态上下文应由调用方放入 user message。
+   */
+  content: string;
+}
+
+/**
+ * 当前 session 的稳定上下文信息。
+ */
+export interface AgentSessionSystemSessionInfo {
+  /**
+   * 当前 session 所属 agentId。
+   */
+  agentId: string;
+
+  /**
+   * 当前 session 唯一标识。
+   */
+  sessionId: string;
+
+  /**
+   * 当前 agent 绑定的项目根目录。
+   */
+  projectRoot: string;
+
+  /**
+   * 当前 session 首次创建时间。
+   *
+   * 关键点（中文）
+   * - 这是 session 初始化时落盘的稳定参考时间，按 Date/ISO 字符串对外展示。
+   * - 它不是每轮运行的当前时间，不会随着 `run()` / `stream()` 改变。
+   */
+  createdAt: string;
+
+  /**
+   * 当前 session 初始化时解析到的系统时区。
+   *
+   * 关键点（中文）
+   * - 这是 session 级参考时区，随创建信息一起固定。
+   * - 它不是每轮运行重新解析的动态时区。
+   */
+  timezone: string;
+}
+
+/**
+ * 当前 session 生效的完整 system prompt 快照。
+ */
+export interface AgentSessionSystemSnapshot {
+  /**
+   * 当前 sessionId。
+   */
+  sessionId: string;
+
+  /**
+   * 当前 session 的稳定上下文信息。
+   *
+   * 关键点（中文）
+   * - 这里包含 session 创建时间这类稳定参考信息。
+   * - 这里不包含当前时间、轮次、用户输入等每轮变化的数据。
+   * - 每轮动态信息应由调用方放入 user message，避免破坏 instruction 缓存命中。
+   */
+  session: AgentSessionSystemSessionInfo;
+
+  /**
+   * 当前生效的 system blocks，按进入模型的顺序排列。
+   */
+  blocks: AgentSessionSystemBlock[];
+}
+
 /**
  * Session 元数据列表项。
  */

package/src/sdk/RemoteAgent.ts

@@ -12,6 +12,7 @@ import type {
   AgentSessionRunResult,
   AgentSessionSetInput,
   AgentSessionStreamEvent,
+  AgentSessionSystemSnapshot,
   RemoteAgentOptions,
 } from "@/sdk/AgentSdkTypes.js";
 import type { SessionMessageV1 } from "@/session/types/SessionMessages.js";
@@ -78,18 +79,23 @@ class RemoteSession {
   }
 
   /**
-   * 读取远程 session 当前生效的 system prompt 文本集合。
+   * 读取远程 session 当前生效的 system prompt 快照。
    */
-  async system(): Promise<string[]> {
+  async system(): Promise<AgentSessionSystemSnapshot> {
     const response = await fetch(
       `${this.baseUrl}/api/sdk/sessions/${encodeURIComponent(this.id)}/system`,
     );
     const payload = (await response.json()) as {
       success?: boolean;
       error?: string;
-      system?: string[];
+      system?: AgentSessionSystemSnapshot;
     };
-    if (!response.ok || !payload.success || !Array.isArray(payload.system)) {
+    if (
+      !response.ok ||
+      !payload.success ||
+      !payload.system ||
+      !Array.isArray(payload.system.blocks)
+    ) {
       throw new Error(String(payload.error || "Remote session system failed"));
     }
     return payload.system;