@downcity/agent 1.1.277 → 1.1.278

package/src/types/agent/SessionActor.ts

@@ -125,6 +125,9 @@ export interface AgentSession extends AgentSessionActor {
   /** 写入当前 session 默认配置。 */
   set(input: AgentSessionSetInput): Promise<void>;
 
+  /** 把当前 Session 生效的自定义 instruction 显式固化到 instruction.md。 */
+  snapshot(): Promise<void>;
+
   /** 从当前 session 创建一个分叉会话。 */
   fork(input?: AgentSessionForkInput | string): Promise<AgentSession>;
 }

package/src/types/session/SessionInstruction.ts

@@ -0,0 +1,24 @@
+/**
+ * Session instruction 显式快照存储类型。
+ *
+ * 关键点（中文）
+ * - 这里只描述 instruction.md 的定位与写入输入。
+ * - 文件存在性本身用于表达 Session 是否启用显式 instruction 快照。
+ */
+
+/** Session instruction.md 的稳定定位信息。 */
+export interface SessionInstructionStorageLocation {
+  /** 当前项目根目录。 */
+  project_root: string;
+  /** 当前 Agent 稳定标识。 */
+  agent_id: string;
+  /** 当前 Session 稳定标识。 */
+  session_id: string;
+}
+
+/** 原子写入 Session instruction.md 使用的完整输入。 */
+export interface WriteSessionInstructionInput
+  extends SessionInstructionStorageLocation {
+  /** 当前 Session 生效的自定义 instruction Markdown。 */
+  instruction: string;
+}

package/src/types/session/SessionOptions.ts

@@ -74,9 +74,13 @@ export interface SessionOptions {
   logger: Logger;
 
   /**
-   * 读取当前 SDK 调用方传入的 instruction system blocks。
+   * 当前 Session 创建时绑定的 instruction system blocks。
+   *
+   * 关键点（中文）
+   * - Session 创建后不再动态读取 Agent instruction。
+   * - `session.snapshot()` 只会把其中 `instruction` 来源的内容显式写入本地文件。
    */
-  getInstructionSystemBlocks: () => AgentSessionSystemBlock[];
+  instruction_system_blocks: AgentSessionSystemBlock[];
 
   /**
    * 读取当前 Agent configured env。

package/src/types/session/SessionQueue.ts

@@ -4,7 +4,7 @@
  * 队列只保存明确的输入事实，不保存可执行闭包。SessionTurn 是这些输入的唯一解释者。
  */
 
-import type { AgentSessionConfigSnapshot, AgentSessionSystemBlock } from "@/types/agent/SessionTypes.js";
+import type { AgentSessionConfigSnapshot } from "@/types/agent/SessionTypes.js";
 import type { AgentPluginExecutionRuntime } from "@/types/plugin/PluginRuntime.js";
 import type { AgentSessionPromptInput } from "@/types/sdk/AgentSessionPrompt.js";
 import type { AgentSessionTurnHandle } from "@/types/sdk/AgentSessionTurn.js";
@@ -23,16 +23,6 @@ export interface SessionModelQueueCommand {
   action_title?: string;
 }
 
-/** Agent instruction 在 Session Step 检查点生效的命令。 */
-export interface SessionInstructionQueueCommand {
-  /** 命令种类固定为 Agent instruction 更新。 */
-  type: "agent_instruction";
-  /** 当前命令的稳定唯一标识。 */
-  command_id: string;
-  /** 下一 Step 使用的完整 instruction blocks。 */
-  instruction_blocks: AgentSessionSystemBlock[];
-}
-
 /** Agent env 在 Session Step 检查点生效的命令。 */
 export interface SessionEnvQueueCommand {
   /** 命令种类固定为 Agent env 更新。 */
@@ -66,29 +56,19 @@ export interface SessionCompactQueueCommand {
 /** Session FIFO 中允许出现的领域命令。 */
 export type SessionQueueCommand =
   | SessionModelQueueCommand
-  | SessionInstructionQueueCommand
   | SessionEnvQueueCommand
   | SessionPluginsQueueCommand
   | SessionCompactQueueCommand;
 
 /** Agent configured state 广播给既有 Session 的输入。 */
-export type AgentSessionCommand =
-  | {
-      /** 当前修改固定为 instruction。 */
-      type: "instruction";
-      /** 当前命令唯一标识。 */
-      command_id: string;
-      /** 下一 Session Step 使用的 instruction blocks。 */
-      instruction_blocks: AgentSessionSystemBlock[];
-    }
-  | {
-      /** 当前修改固定为 env。 */
-      type: "env";
-      /** 当前命令唯一标识。 */
-      command_id: string;
-      /** 下一 Session Step 使用的完整 Agent env。 */
-      env: Record<string, string>;
-    }
+export type AgentSessionCommand = {
+    /** 当前修改固定为 env。 */
+    type: "env";
+    /** 当前命令唯一标识。 */
+    command_id: string;
+    /** 下一 Session Step 使用的完整 Agent env。 */
+    env: Record<string, string>;
+  }
   | {
       /** 当前修改固定为 plugins。 */
       type: "plugins";