@downcity/agent 1.1.10 → 1.1.12

package/src/{agent → runtime}/AgentRuntimeTypes.ts

@@ -9,12 +9,12 @@
 
 import type { LanguageModel } from "ai";
 import type { Logger } from "@/utils/logger/Logger.js";
-import type { DowncityConfig } from "@/config/types/DowncityConfig.js";
+import type { DowncityConfig } from "@/types/config/DowncityConfig.js";
 import type {
   AgentPathRuntime,
   AgentPlatformRuntime,
   AgentPluginConfigRuntime,
-} from "@/host/types/AgentHost.js";
+} from "@/types/host/AgentHost.js";
 import type { BaseService } from "@/service/builtins/BaseService.js";
 import type { Session } from "@session/Session.js";
 

package/src/sandbox/SandboxConfigResolver.ts

@@ -8,7 +8,7 @@
  */
 
 import path from "node:path";
-import type { AgentContext } from "@/agent/AgentContextTypes.js";
+import type { AgentContext } from "@/runtime/AgentContextTypes.js";
 import type { ResolvedSandboxConfig } from "@/sandbox/types/SandboxRuntime.js";
 
 const DEFAULT_ENV_ALLOWLIST = [

package/src/sandbox/SandboxRunner.ts

@@ -7,7 +7,7 @@
  * - shell 命令不再允许回退到宿主机普通子进程执行。
  */
 
-import type { AgentContext } from "@/agent/AgentContextTypes.js";
+import type { AgentContext } from "@/runtime/AgentContextTypes.js";
 import type { SandboxSpawnResult } from "@/sandbox/types/SandboxRuntime.js";
 import { resolveSandboxConfig, resolveSandboxCwd } from "@/sandbox/SandboxConfigResolver.js";
 import { spawnMacOsSeatbeltSandbox } from "@/sandbox/MacOsSeatbeltSandbox.js";

package/src/{host/sdk → 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 运行协议，而不是重复实现一套执行链。
  */
@@ -12,11 +12,11 @@ import { nanoid } from "nanoid";
 import type { Tool } from "ai";
 import { Logger } from "@/utils/logger/Logger.js";
 import type { BaseService } from "@/service/builtins/BaseService.js";
-import type { AgentContext } from "@/agent/AgentContextTypes.js";
-import type { AgentRuntime } from "@/agent/AgentRuntimeTypes.js";
-import type { DowncityConfig } from "@/config/types/DowncityConfig.js";
-import type { JsonValue } from "@/utils/types/Json.js";
-import type { AgentPlatformRuntime } from "@/host/types/AgentHost.js";
+import type { AgentContext } from "@/runtime/AgentContextTypes.js";
+import type { AgentRuntime } from "@/runtime/AgentRuntimeTypes.js";
+import type { DowncityConfig } from "@/types/config/DowncityConfig.js";
+import type { JsonValue } from "@/types/common/Json.js";
+import type { AgentPlatformRuntime } from "@/types/host/AgentHost.js";
 import type {
   Plugin,
   PluginAvailability,
@@ -26,12 +26,13 @@ import type {
 import type {
   AgentOptions,
   AgentSessionMetadata,
-} from "@/host/sdk/AgentSdkTypes.js";
-import { SdkSession } from "@/host/sdk/Session.js";
-import { loadStaticSystemPrompts } from "@session/composer/system/default/StaticPromptCatalog.js";
-import { getSdkAgentSessionsRootDirPath } from "@/host/sdk/Paths.js";
-import { SdkAgentHttpServer } from "@/host/sdk/HttpServer.js";
-import { SdkAgentRpcServer } from "@/host/sdk/RpcServer.js";
+  AgentSessionSystemBlock,
+} from "@/sdk/AgentSdkTypes.js";
+import { SdkSession } 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";
 import {
   createAgentPathRuntime,
   createAgentPluginConfigRuntime,
@@ -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。
  */
@@ -90,7 +126,7 @@ export class Agent {
   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();
@@ -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,
@@ -409,9 +461,9 @@ export class Agent {
       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/{host/sdk → sdk}/AgentSdkTypes.ts

@@ -9,10 +9,10 @@
 
 import type { LanguageModel, Tool } from "ai";
 import type { BaseService } from "@/service/builtins/BaseService.js";
-import type { JsonValue } from "@/utils/types/Json.js";
+import type { JsonValue } from "@/types/common/Json.js";
 import type { Plugin } from "@/plugin/types/Plugin.js";
 import type { SessionMessageV1 } from "@/session/types/SessionMessages.js";
-import type { AgentPlatformRuntime } from "@/host/types/AgentHost.js";
+import type { AgentPlatformRuntime } from "@/types/host/AgentHost.js";
 
 /**
  * 本地 Agent 构造参数。
@@ -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/{host/sdk → sdk}/HttpServer.ts

@@ -9,7 +9,7 @@
 import http from "node:http";
 import { Hono } from "hono";
 import { cors } from "hono/cors";
-import type { Agent } from "@/host/sdk/Agent.js";
+import type { Agent } from "@/sdk/Agent.js";
 
 type SdkHttpStartOptions = {
   /**
@@ -86,6 +86,15 @@ export class SdkAgentHttpServer {
       });
     });
 
+    app.get("/api/sdk/sessions/:sessionId/system", async (c) => {
+      const session = await this.agent.session(String(c.req.param("sessionId") || ""));
+      return c.json({
+        success: true,
+        sessionId: session.id,
+        system: await session.system(),
+      });
+    });
+
     app.post("/api/sdk/sessions/:sessionId/run", async (c) => {
       const session = await this.agent.session(String(c.req.param("sessionId") || ""));
       const body = await c.req.json().catch(() => ({}));

package/src/{host/sdk → sdk}/RemoteAgent.ts

@@ -12,8 +12,9 @@ import type {
   AgentSessionRunResult,
   AgentSessionSetInput,
   AgentSessionStreamEvent,
+  AgentSessionSystemSnapshot,
   RemoteAgentOptions,
-} from "@/host/sdk/AgentSdkTypes.js";
+} from "@/sdk/AgentSdkTypes.js";
 import type { SessionMessageV1 } from "@/session/types/SessionMessages.js";
 
 /**
@@ -77,6 +78,29 @@ class RemoteSession {
     return payload.messages;
   }
 
+  /**
+   * 读取远程 session 当前生效的 system prompt 快照。
+   */
+  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?: AgentSessionSystemSnapshot;
+    };
+    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;
+  }
+
   /**
    * 分叉远程 session。
    */

package/src/{host/sdk → sdk}/RpcServer.ts

@@ -10,12 +10,12 @@
 import fs from "fs-extra";
 import net, { type Server } from "node:net";
 import path from "node:path";
-import type { Agent } from "@/host/sdk/Agent.js";
+import type { Agent } from "@/sdk/Agent.js";
 import type {
   LocalRpcRequest,
   LocalRpcResponse,
-} from "@/host/rpc/types/LocalRpc.js";
-import { getSdkAgentRpcEndpointPath } from "@/host/sdk/Paths.js";
+} from "@/types/rpc/LocalRpc.js";
+import { getSdkAgentRpcEndpointPath } from "@/sdk/Paths.js";
 
 /**
  * SDK RPC Server 管理器。
@@ -208,6 +208,24 @@ export class SdkAgentRpcServer {
         };
       }
 
+      const systemMatch =
+        /^\/api\/sdk\/sessions\/([^/]+)\/system$/.exec(request.path);
+      if (request.method === "GET" && systemMatch) {
+        const session = await this.agent.session(
+          decodeURIComponent(systemMatch[1] || ""),
+        );
+        return {
+          requestId,
+          status: 200,
+          success: true,
+          data: {
+            success: true,
+            sessionId: session.id,
+            system: await session.system(),
+          } as unknown as LocalRpcResponse["data"],
+        };
+      }
+
       return {
         requestId,
         status: 404,