`session.system()`

示例

const system = await session.system();

它返回什么

返回结构化 system snapshot：

{
  session_id: string;
  session: {
    agent_id: string;
    session_id: string;
    project_root: string;
    created_at: string;
    timezone: string;
  };
  blocks: Array<{
    source: "core" | "instruction" | "plugin" | "session";
    name: string;
    content: string;
  }>;
}

这些 blocks 可以包括：

调用方传入的静态 instruction
Downcity Agent core 说明，包括 Harness 设计思路、Shell command 规则和 plugin 系统总规则
已注册并启用的 plugin system 文本
稳定的 session 上下文，包括 agent_id、session_id、project_root、创建时间与时区

返回内容和 session.prompt() 使用的是同一套稳定 system blocks。system 第一次生成后会固定在当前 Session 内存中；后续 Agent instruction 或 plugin registry 变化不会修改它。新 Session 才会使用最新配置生成 system。

需要让已有本地 Session 显式采用 Agent 当前配置时，调用 session.syncshot()。

session 创建时间和时区是当前会话的参考时间上下文。当前时间等动态值应放入 user message，不应放进 instruction。

Block 顺序

@downcity/agent 会按固定顺序构造 system blocks：

instruction：宿主传入的 Agent 角色、业务规则和回复偏好。
core：Downcity Agent 固定运行说明，包括 Harness 设计思路、Shell command 与 plugin 系统总规则。
plugin：每个已经启用、已 ready 且当前可用的 plugin 自己的 system prompt。
session：当前 session 的稳定上下文。

即使宿主传入了 instruction，core 也会继续注入，并紧跟在 instruction 后面。

示例快照

{
  "session_id": "design-review",
  "session": {
    "agent_id": "city-dev",
    "session_id": "design-review",
    "project_root": "/path/to/project",
    "created_at": "2026-05-19T14:16:25.048Z",
    "timezone": "Asia/Shanghai"
  },
  "blocks": [
    {
      "source": "instruction",
      "name": "agent",
      "content": "你是 Downcity 的项目助手。"
    },
    {
      "source": "core",
      "name": "default",
      "content": "# Downcity Agent\n\nYou are a Downcity Agent running inside the Downcity Agent runtime...\n\n# Harness Design\n\nDowncity Agent is a harness around an existing human-owned workspace, not a replacement platform...\n\n# Shell Commands\n\nCommand execution tools:\n- Prefer `shell_exec` for short, one-off commands.\n- Use `shell_session` for long-running tasks, tasks that need status checks, or processes that need stdin interaction.\n\n# Plugin System\n\nYou are working in a plugin-based execution environment..."
    },
    {
      "source": "plugin",
      "name": "task",
      "content": "# Task Plugin\n\nThe task plugin manages scheduled and repeatable tasks..."
    },
    {
      "source": "session",
      "name": "context",
      "content": "Current session context:\nYou are serving agent \"city-dev\" in session \"design-review\".\nThe current project root is \"/path/to/project\".\nThis session was created at 2026-05-19T14:16:25.048Z, with Asia/Shanghai as its reference timezone.\nThis creation time is a stable reference for the session and does not represent the current time for every run.\nIf the user message provides a newer current time, a relative time, or other dynamic context, prioritize the dynamic information from the user message."
    }
  ]
}

它不会做什么

session.system() 不会把 system prompt 写进 active.jsonl 或历史 Segment。

Session history 仍然只关注可见的 user / assistant 消息。如果你需要检查当前会随历史一起进入模型的提示词上下文，用 system()。

session.system()