@downcity/agent 1.1.25 → 1.1.32

package/src/sdk/session/runtime/SessionPromptRuntime.ts

@@ -9,7 +9,9 @@
 
 import { nanoid } from "nanoid";
 import type { SessionUserMessageV1 } from "@/session/types/SessionMessages.js";
+import type { SessionMessageV1 } from "@/session/types/SessionMessages.js";
 import type { AgentSessionEvent } from "@/types/sdk/AgentSessionEvent.js";
+import type { AgentSessionPromptInput } from "@/types/sdk/AgentSessionPrompt.js";
 import type {
   AgentSessionTurnHandle,
   AgentSessionTurnResult,
@@ -17,9 +19,9 @@ import type {
 
 type QueuedPrompt = {
   /**
-   * 当前排队中的用户文本。
+   * 当前排队中的 prompt 输入。
    */
-  query: string;
+  input: AgentSessionPromptInput;
 
   /**
    * 当前 prompt 对应的 turn handle Promise 控制器。
@@ -79,18 +81,21 @@ export interface SessionPromptRuntimeOptions {
   /**
    * 构造并持久化一条 user 消息。
    */
-  createAndPersistUserMessage: (query: string) => Promise<SessionUserMessageV1>;
+  createAndPersistUserMessage: (
+    input: AgentSessionPromptInput,
+  ) => Promise<SessionUserMessageV1>;
 
   /**
    * 执行单轮 turn。
    */
   executeTurn: (input: {
     turnId: string;
-    query: string;
+    promptInput: AgentSessionPromptInput;
     onStepMerge: () => Promise<SessionUserMessageV1[]>;
   }) => Promise<{
     text: string;
     success: boolean;
+    assistantMessage: SessionMessageV1;
     error?: string;
   }>;
 }
@@ -119,10 +124,12 @@ export class SessionPromptRuntime {
   /**
    * 追加一条新的 prompt。
    */
-  prompt(query: string): Promise<AgentSessionTurnHandle> {
+  prompt(input: AgentSessionPromptInput): Promise<AgentSessionTurnHandle> {
     const deferredHandle = createDeferred<AgentSessionTurnHandle>();
     this.queue.push({
-      query: String(query || "").trim(),
+      input: {
+        query: String(input.query || "").trim(),
+      },
       deferredHandle,
     });
     this.ensureProcessing();
@@ -164,10 +171,10 @@ export class SessionPromptRuntime {
       current.deferredHandle.resolve(createTurnHandle(activeTurn));
 
       try {
-        await this.createAndPersistUserMessage(current.query);
+        await this.createAndPersistUserMessage(current.input);
         const result = await this.executeTurn({
           turnId,
-          query: current.query,
+          promptInput: current.input,
           onStepMerge: async () => {
             return await this.drainQueuedPromptsAsMessages(activeTurn);
           },
@@ -176,6 +183,7 @@ export class SessionPromptRuntime {
           turnId,
           text: result.text,
           success: result.success,
+          assistantMessage: result.assistantMessage,
           ...(result.error ? { error: result.error } : {}),
         };
         activeTurn.result = finalResult;
@@ -193,6 +201,10 @@ export class SessionPromptRuntime {
           turnId,
           text: "",
           success: false,
+          assistantMessage: buildPromptRuntimeErrorAssistantMessage({
+            sessionId: this.sessionId,
+            message,
+          }),
           error: message,
         };
         activeTurn.result = finalResult;
@@ -220,12 +232,12 @@ export class SessionPromptRuntime {
     const merged: SessionUserMessageV1[] = [];
 
     for (let index = 0; index < drained.length; index += 1) {
-      const item = drained[index];
-      try {
-        const message = await this.createAndPersistUserMessage(item.query);
-        item.deferredHandle.resolve(createTurnHandle(activeTurn));
-        merged.push(message);
-      } catch {
+        const item = drained[index];
+        try {
+          const message = await this.createAndPersistUserMessage(item.input);
+          item.deferredHandle.resolve(createTurnHandle(activeTurn));
+          merged.push(message);
+        } catch {
         // 关键点（中文）：若某条消息持久化失败，把未处理部分重新放回队列头部，避免静默丢失。
         const remaining = drained.slice(index);
         this.queue.unshift(...remaining);
@@ -237,6 +249,27 @@ export class SessionPromptRuntime {
   }
 }
 
+function buildPromptRuntimeErrorAssistantMessage(input: {
+  sessionId: string;
+  message: string;
+}): SessionMessageV1 {
+  return {
+    id: `a:${input.sessionId}:${Date.now()}:${nanoid(6)}`,
+    role: "assistant",
+    metadata: {
+      v: 1,
+      ts: Date.now(),
+      sessionId: input.sessionId,
+      source: "egress",
+      kind: "normal",
+      extra: {
+        note: "session_prompt_runtime_error",
+      },
+    },
+    parts: [{ type: "text", text: input.message }],
+  };
+}
+
 function createDeferred<T>(): Deferred<T> {
   let resolve!: (value: T) => void;
   const promise = new Promise<T>((innerResolve) => {

package/src/session/composer/system/default/SystemDomain.ts

@@ -2,7 +2,7 @@
  * SystemDomain：system 领域统一实现。
  *
  * 关键点（中文）
- * - 收敛 system 的资产加载、上下文档位判定、service prompt 收集、messages 组装。
+ * - 收敛 system 的资产加载、上下文档位判定、plugin prompt 收集、messages 组装。
  * - `DefaultSessionSystemComposer` 只做组件适配；核心逻辑统一在本文件。
  */
 
@@ -10,16 +10,16 @@ import type { SystemModelMessage } from "ai";
 import { transformPromptsIntoSystemMessages } from "@session/composer/system/default/PromptRenderer.js";
 import { isPluginEnabled } from "@/plugin/core/Activation.js";
 import { PLUGINS } from "@/plugin/core/Plugins.js";
-import { SERVICE_SYSTEM_PROVIDERS } from "@/service/core/ServiceSystemProviders.js";
+import { PLUGIN_SYSTEM_PROVIDERS } from "@/plugin/core/PluginSystemProviders.js";
 import type { AgentContext } from "@/core/AgentContextTypes.js";
 import { buildRuntimeClockSystemPrompt } from "@session/composer/system/default/variables/VariableReplacer.js";
 import {
   CORE_SYSTEM_PROMPT,
-  SERVICE_SYSTEM_PROMPT,
+  PLUGIN_SYSTEM_PROMPT,
   TASK_SYSTEM_PROMPT,
 } from "@session/composer/system/default/SystemPromptAssets.js";
 
-const DEFAULT_DISABLED_SERVICE_NAMES: string[] = [];
+const DEFAULT_DISABLED_RUNTIME_PLUGIN_NAMES: string[] = [];
 
 function normalizeSystemText(input: string | null | undefined): string {
   return String(input || "").trim();
@@ -30,7 +30,7 @@ function normalizeSystemText(input: string | null | undefined): string {
  */
 export const DEFAULT_SHIP_PROMPTS = CORE_SYSTEM_PROMPT;
 
-const MAIN_SERVICE_PROMPT = SERVICE_SYSTEM_PROMPT;
+const MAIN_PLUGIN_PROMPT = PLUGIN_SYSTEM_PROMPT;
 
 /**
  * 构建一次运行的运行时 system prompt。
@@ -111,7 +111,7 @@ export function resolveStaticSystemPrompts(input: {
 type ResolvedSystemContextProfile = {
   mode: "chat" | "task";
   replaceDefaultCorePrompt?: string;
-  disableServiceSystems: string[];
+  disablePluginSystems: string[];
 };
 
 /**
@@ -126,8 +126,8 @@ export type SystemProfile = "chat" | "task";
  * 按显式 profile 解析 system 上下文档位。
  *
  * 关键点（中文）
- * - chat 模式：使用默认 core prompt 与全部 service system。
- * - task 模式：自动替换 task core prompt，并禁用 chat service system。
+ * - chat 模式：使用默认 core prompt 与全部 plugin system。
+ * - task 模式：自动替换 task core prompt，并禁用 chat plugin system。
  */
 export function resolveSystemContextProfile(
   profile?: SystemProfile,
@@ -135,50 +135,50 @@ export function resolveSystemContextProfile(
   if (profile !== "task") {
     return {
       mode: "chat",
-      disableServiceSystems: [...DEFAULT_DISABLED_SERVICE_NAMES],
+      disablePluginSystems: [...DEFAULT_DISABLED_RUNTIME_PLUGIN_NAMES],
     };
   }
   return {
     mode: "task",
     replaceDefaultCorePrompt: TASK_SYSTEM_PROMPT,
-    disableServiceSystems: ["chat"],
+    disablePluginSystems: ["chat"],
   };
 }
 
 /**
- * 收集 service 维度的 system 文本。
+ * 收集 runtime plugin 维度的 system 文本。
  *
  * 关键点（中文）
- * - 顺序：main service prompt -> service.system。
+ * - 顺序：main plugin prompt -> plugin.system。
  * - 单个加载失败走 fail-open，不阻断主链路。
  */
-export async function loadServiceSystemPrompts(input: {
+export async function loadRuntimePluginSystemPrompts(input: {
   /**
    * 当前执行上下文。
    */
   context: AgentContext;
 
   /**
-   * 当前轮禁用的 service 名称集合。
+   * 当前轮禁用的 plugin 名称集合。
    */
-  disabledServiceNames: string[];
+  disabledPluginNames: string[];
 }): Promise<string[]> {
   const out: string[] = [];
-  const mainServicePrompt = normalizeSystemText(MAIN_SERVICE_PROMPT);
-  if (mainServicePrompt) {
-    out.push(mainServicePrompt);
+  const mainPluginPrompt = normalizeSystemText(MAIN_PLUGIN_PROMPT);
+  if (mainPluginPrompt) {
+    out.push(mainPluginPrompt);
   }
 
-  const disabledServiceNames = new Set(
-    input.disabledServiceNames
+  const disabledPluginNames = new Set(
+    input.disabledPluginNames
       .map((item) => String(item || "").trim())
       .filter(Boolean),
   );
 
-  for (const service of SERVICE_SYSTEM_PROVIDERS) {
-    if (disabledServiceNames.has(service.name)) continue;
+  for (const plugin of PLUGIN_SYSTEM_PROVIDERS) {
+    if (disabledPluginNames.has(plugin.name)) continue;
     try {
-      const text = normalizeSystemText(await service.system(input.context));
+      const text = normalizeSystemText(await plugin.system(input.context));
       if (!text) continue;
       out.push(text);
     } catch {
@@ -190,14 +190,14 @@ export async function loadServiceSystemPrompts(input: {
 }
 
 /**
- * 收集 plugin 维度的 system 文本。
+ * 收集扩展型 plugin 的 system 文本。
  *
  * 关键点（中文）
- * - plugin.system 在语义上属于“增强注入”，不再要求能力必须伪装成 service。
+ * - extension plugin 的 `plugin.system` 在语义上属于“增强注入”。
  * - 若 plugin 显式声明 availability 且当前 unavailable，则跳过其 system 注入。
  * - 单个 plugin 加载失败走 fail-open，不阻断主链路。
  */
-export async function loadPluginSystemPrompts(input: {
+export async function loadExtensionPluginSystemPrompts(input: {
   /**
    * 当前统一执行上下文。
    */
@@ -235,7 +235,7 @@ export async function loadPluginSystemPrompts(input: {
  * 统一构建一次 Session 运行所需的 system messages。
  *
  * 关键点（中文）
- * - context/static/service 的组装逻辑统一收敛在 system 域。
+ * - context/static/plugin 的组装逻辑统一收敛在 system 域。
  */
 export async function buildSessionSystemMessages(input: {
   /**
@@ -264,14 +264,14 @@ export async function buildSessionSystemMessages(input: {
   staticSystemPrompts: string[];
 
   /**
-   * service system 文本集合（main service + services + memory）。
+   * runtime plugin system 文本集合（main plugin + builtin runtime plugins）。
    */
-  serviceSystemPrompts: string[];
+  runtimePluginSystemPrompts: string[];
 
   /**
-   * plugin system 文本集合。
+   * extension plugin system 文本集合。
    */
-  pluginSystemPrompts: string[];
+  extensionPluginSystemPrompts: string[];
 }): Promise<SystemModelMessage[]> {
   const runtimeClockText = buildRuntimeClockSystemPrompt({
     projectPath: input.projectRoot,
@@ -300,16 +300,20 @@ export async function buildSessionSystemMessages(input: {
     },
   );
 
-  const serviceSystemMessages = await transformPromptsIntoSystemMessages(
-    Array.isArray(input.serviceSystemPrompts) ? input.serviceSystemPrompts : [],
+  const runtimePluginSystemMessages = await transformPromptsIntoSystemMessages(
+    Array.isArray(input.runtimePluginSystemPrompts)
+      ? input.runtimePluginSystemPrompts
+      : [],
     {
       projectPath: input.projectRoot,
       variableMode: "stable",
     },
   );
 
-  const pluginSystemMessages = await transformPromptsIntoSystemMessages(
-    Array.isArray(input.pluginSystemPrompts) ? input.pluginSystemPrompts : [],
+  const extensionPluginSystemMessages = await transformPromptsIntoSystemMessages(
+    Array.isArray(input.extensionPluginSystemPrompts)
+      ? input.extensionPluginSystemPrompts
+      : [],
     {
       projectPath: input.projectRoot,
       variableMode: "stable",
@@ -318,15 +322,15 @@ export async function buildSessionSystemMessages(input: {
 
   return [
     ...staticSystemMessages,
-    ...serviceSystemMessages,
-    ...pluginSystemMessages,
+    ...runtimePluginSystemMessages,
+    ...extensionPluginSystemMessages,
     ...runtimeRuleMessages,
     ...runtimeClockMessages,
   ];
 }
 
 /**
- * 统一解析一次 Session 运行所需的 system messages（含上下文档位判定与 service 收集）。
+ * 统一解析一次 Session 运行所需的 system messages（含上下文档位判定与 plugin 收集）。
  */
 export async function resolveSessionSystemMessages(input: {
   /**
@@ -362,11 +366,11 @@ export async function resolveSessionSystemMessages(input: {
     mode: profile.mode,
     replaceDefaultCorePrompt: profile.replaceDefaultCorePrompt,
     staticSystemPrompts: input.staticSystemPrompts,
-    serviceSystemPrompts: await loadServiceSystemPrompts({
+    runtimePluginSystemPrompts: await loadRuntimePluginSystemPrompts({
       context: input.context,
-      disabledServiceNames: profile.disableServiceSystems,
+      disabledPluginNames: profile.disablePluginSystems,
     }),
-    pluginSystemPrompts: await loadPluginSystemPrompts({
+    extensionPluginSystemPrompts: await loadExtensionPluginSystemPrompts({
       context: input.context,
     }),
   });

package/src/session/composer/system/default/SystemPromptAssets.ts

@@ -7,7 +7,7 @@
  */
 
 import coreSystemPromptText from "@session/composer/system/default/assets/core.prompt.js";
-import serviceSystemPromptText from "@session/composer/system/default/assets/service.prompt.js";
+import pluginSystemPromptText from "@session/composer/system/default/assets/plugin.prompt.js";
 import taskSystemPromptText from "@session/composer/system/default/assets/task.prompt.js";
 
 /**
@@ -16,9 +16,9 @@ import taskSystemPromptText from "@session/composer/system/default/assets/task.p
 export const CORE_SYSTEM_PROMPT = coreSystemPromptText.trim();
 
 /**
- * service 层稳定 system prompt。
+ * plugin 层稳定 system prompt。
  */
-export const SERVICE_SYSTEM_PROMPT = serviceSystemPromptText.trim();
+export const PLUGIN_SYSTEM_PROMPT = pluginSystemPromptText.trim();
 
 /**
  * task 模式专用 system prompt。

package/src/session/composer/system/default/assets/core.prompt.ts

@@ -4,6 +4,6 @@
  */
 
 // Source: src/session/composer/system/default/assets/core.prompt.ts.txt
-const TEXT_MODULE_CONTENT = "你拥有且仅拥有当前项目 {{project_path}} 的使用权和修改权。当前年份是 {{current_year}} 年。\n1. `.downcity/` 是 Downcity 的运行时数据目录（通常不需要你手动读取/修改；系统会自动写入与注入）。结构与逻辑如下：\n   - `.downcity/session/` 是会话消息。\n   - `.downcity/memory/` 是中长期记忆。\n   - `.downcity/profile/Primary.md`、`.downcity/profile/other.md`：全局 profile 记忆；存在时会自动作为 system prompt 注入。\n   - `.downcity/public/`：对外静态资源目录，通过 `GET /downcity/public/<path>` 访问；用于给外部访问的路径。不要存放敏感信息，运行中的 agent server 会把 `.downcity/public/` 暴露为 HTTP 静态资源：`GET /downcity/public/<path>`，你可以把该 URL 发给用户用于下载/查看生成的文件（注意不要暴露敏感信息）。\n   - `.downcity/logs/<YYYY-MM-DD>.jsonl`：运行日志（JSONL）；用于排查问题，避免把原始日志整段贴给用户。\n   - `.downcity/.cache/`：幂等/去重缓存（ingress/egress）；不要手动改。\n   - `.downcity/.debug/`：调试产物（daemon pid/log/meta、适配器事件抓取等）；仅在排查问题时查看。\n   - `.downcity/data/`：小型持久化数据（预留）。\n   - `.downcity/task/`：Task 目录。\n2. PROFILE.md + SOUL.md + downcity.json 是你的一些配置文件，你不需要读取。\n\n# 最重要\n【关于命令执行工具】（重要）\n- 短命令、一次性命令优先使用 `shell_exec`。\n- 长任务、需要中途查状态、需要 stdin 交互时，使用 `shell_start` / `shell_status` / `shell_read` / `shell_write` / `shell_wait` / `shell_close`。\n- 先用 `shell_start` 启动命令并拿到 `shell_id`。\n- `shell_id` 是 shell 会话标识；它不是 chat `session_id`。\n- 长任务期间，优先使用 `shell_status` 查询进度，或使用 `shell_wait` 等待状态变化；不要自己写高频空轮询循环。\n- 只有在确实需要原始增量输出时，才使用 `shell_read` 按 `from_cursor` 继续读取。\n- 需要向进程 stdin 输入内容时，使用 `shell_write`。\n- 命令会话完成后若不再需要，使用 `shell_close` 主动释放资源。\n- 不要把原始超长 shell 输出直接转发给用户，应先总结。\n\n# 默认决策与澄清\n- 默认先执行，再沟通：对低风险、可回滚、用户意图已经足够明显的请求，优先基于当前日期、时区、聊天上下文与常见默认值直接执行，不要在事件标题、默认平台、显然的时间表达上反复追问。\n- 只有当“缺失信息会实质改变结果”时才追问；例如：会影响日期/对象/金额/账户/发送目标，或会触发不可逆、高风险、涉隐私操作。\n- 处理时间表达时，优先使用当前环境提供的 `current_date`、`current_time` 与 `timezone`；如果入站 `<info>` 明确提供了 `user_timezone`，则优先按 `user_timezone` 解析，否则按 runtime clock 的 `timezone` 解析。像“今天/明天/下午两点/提前两小时”这类表达，应先解析为绝对时间，再执行，并在回复里明确写出绝对日期时间。\n- 当任务依赖外部权限、系统能力或第三方连接（如日历、提醒事项、聊天渠道、系统授权）时，先探测可用性，再决定是否承诺“我来创建/发送/写入”。\n- 如果探测结果显示被系统权限、宿主环境或连接状态阻塞，要直接说明真实阻塞点和下一步，而不是先给出“可以，我来做”的承诺后再多轮追问。\n- 若已经有足够信息可以一次完成多个低风险默认动作，应直接完成，并在结果里简短说明采用了哪些默认假设。\n\n# 很重要\n\n安全与边界\n- 不要执行破坏性命令（如 `rm -rf`、`git reset --hard`）除非用户明确要求。\n- 遇到 API Key、Token、Secret、环境变量、bot 凭据等密钥管理问题时，优先指导用户使用 Console（如 `Global / Env`、`Global / Channel Accounts`）维护，不要要求用户把密钥明文直接发送到当前聊天里。\n- `city keys` 只能列出已配置的 key 名与描述，不会返回密钥值。不要让用户把密钥“发给你自己”或继续尝试通过 `city keys` 获取明文。\n";
+const TEXT_MODULE_CONTENT = "你拥有且仅拥有当前项目 {{project_path}} 的使用权和修改权。当前年份是 {{current_year}} 年。\n1. `.downcity/` 是 Downcity 的运行时数据目录（通常不需要你手动读取/修改；系统会自动写入与注入）。结构与逻辑如下：\n   - `.downcity/agents/<agentId>/sessions/` 是会话消息。\n   - `.downcity/memory/` 是中长期记忆。\n   - `.downcity/profile/Primary.md`、`.downcity/profile/other.md`：全局 profile 记忆；存在时会自动作为 system prompt 注入。\n   - `.downcity/public/`：对外静态资源目录，通过 `GET /downcity/public/<path>` 访问；用于给外部访问的路径。不要存放敏感信息，运行中的 agent server 会把 `.downcity/public/` 暴露为 HTTP 静态资源：`GET /downcity/public/<path>`，你可以把该 URL 发给用户用于下载/查看生成的文件（注意不要暴露敏感信息）。\n   - `.downcity/logs/<YYYY-MM-DD>.jsonl`：运行日志（JSONL）；用于排查问题，避免把原始日志整段贴给用户。\n   - `.downcity/.cache/`：幂等/去重缓存（ingress/egress）；不要手动改。\n   - `.downcity/.debug/`：调试产物（daemon pid/log/meta、适配器事件抓取等）；仅在排查问题时查看。\n   - `.downcity/data/`：小型持久化数据（预留）。\n   - `.downcity/task/`：Task 目录。\n2. PROFILE.md + SOUL.md + downcity.json 是你的一些配置文件，你不需要读取。\n\n# 最重要\n【关于命令执行工具】（重要）\n- 短命令、一次性命令优先使用 `shell_exec`。\n- 长任务、需要中途查状态、需要 stdin 交互时，使用 `shell_start` / `shell_status` / `shell_read` / `shell_write` / `shell_wait` / `shell_close`。\n- 先用 `shell_start` 启动命令并拿到 `shell_id`。\n- `shell_id` 是 shell 会话标识；它不是 chat `session_id`。\n- 长任务期间，优先使用 `shell_status` 查询进度，或使用 `shell_wait` 等待状态变化；不要自己写高频空轮询循环。\n- 只有在确实需要原始增量输出时，才使用 `shell_read` 按 `from_cursor` 继续读取。\n- 需要向进程 stdin 输入内容时，使用 `shell_write`。\n- 命令会话完成后若不再需要，使用 `shell_close` 主动释放资源。\n- 不要把原始超长 shell 输出直接转发给用户，应先总结。\n\n# 默认决策与澄清\n- 默认先执行，再沟通：对低风险、可回滚、用户意图已经足够明显的请求，优先基于当前日期、时区、聊天上下文与常见默认值直接执行，不要在事件标题、默认平台、显然的时间表达上反复追问。\n- 只有当“缺失信息会实质改变结果”时才追问；例如：会影响日期/对象/金额/账户/发送目标，或会触发不可逆、高风险、涉隐私操作。\n- 处理时间表达时，优先使用当前环境提供的 `current_date`、`current_time` 与 `timezone`；如果入站 `<info>` 明确提供了 `user_timezone`，则优先按 `user_timezone` 解析，否则按 runtime clock 的 `timezone` 解析。像“今天/明天/下午两点/提前两小时”这类表达，应先解析为绝对时间，再执行，并在回复里明确写出绝对日期时间。\n- 当任务依赖外部权限、系统能力或第三方连接（如日历、提醒事项、聊天渠道、系统授权）时，先探测可用性，再决定是否承诺“我来创建/发送/写入”。\n- 如果探测结果显示被系统权限、宿主环境或连接状态阻塞，要直接说明真实阻塞点和下一步，而不是先给出“可以，我来做”的承诺后再多轮追问。\n- 若已经有足够信息可以一次完成多个低风险默认动作，应直接完成，并在结果里简短说明采用了哪些默认假设。\n\n# 很重要\n\n安全与边界\n- 不要执行破坏性命令（如 `rm -rf`、`git reset --hard`）除非用户明确要求。\n- 遇到 API Key、Token、Secret、环境变量、bot 凭据等密钥管理问题时，优先指导用户使用 Console（如 `Global / Env`、`Global / Channel Accounts`）维护，不要要求用户把密钥明文直接发送到当前聊天里。\n- `city keys` 只能列出已配置的 key 名与描述，不会返回密钥值。不要让用户把密钥“发给你自己”或继续尝试通过 `city keys` 获取明文。\n";
 
 export default TEXT_MODULE_CONTENT;

package/src/session/composer/system/default/assets/core.prompt.ts.txt

@@ -1,6 +1,6 @@
 你拥有且仅拥有当前项目 {{project_path}} 的使用权和修改权。当前年份是 {{current_year}} 年。
 1. `.downcity/` 是 Downcity 的运行时数据目录（通常不需要你手动读取/修改；系统会自动写入与注入）。结构与逻辑如下：
-   - `.downcity/session/` 是会话消息。
+   - `.downcity/agents/<agentId>/sessions/` 是会话消息。
    - `.downcity/memory/` 是中长期记忆。
    - `.downcity/profile/Primary.md`、`.downcity/profile/other.md`：全局 profile 记忆；存在时会自动作为 system prompt 注入。
    - `.downcity/public/`：对外静态资源目录，通过 `GET /downcity/public/<path>` 访问；用于给外部访问的路径。不要存放敏感信息，运行中的 agent server 会把 `.downcity/public/` 暴露为 HTTP 静态资源：`GET /downcity/public/<path>`，你可以把该 URL 发给用户用于下载/查看生成的文件（注意不要暴露敏感信息）。

package/src/session/composer/system/default/assets/plugin.prompt.ts

@@ -0,0 +1,9 @@
+/**
+ * 自动生成文件，请勿手改。
+ * 源文件：由同路径 `*.ts.txt` 生成。
+ */
+
+// Source: src/session/composer/system/default/assets/plugin.prompt.ts.txt
+const TEXT_MODULE_CONTENT = "# Plugin State\n\n你正在一个基于 plugin 的执行环境中工作。\n\n## 可用命令总览\n- plugin 状态管理（统一使用 `city plugin`）：\n  - `city plugin list`\n  - `city plugin status <pluginName>`\n  - `city plugin start <pluginName>`\n  - `city plugin stop <pluginName>`\n  - `city plugin restart <pluginName>`\n  - `city plugin command <pluginName> <command> [--payload '<json>']`\n  - `city plugin schedule list`\n  - `city plugin schedule info <jobId>`\n  - `city plugin schedule cancel <jobId>`\n- 当前内建 runtime plugin：`shell` / `chat` / `task` / `memory` / `contact` / `schedule`。\n- 当前内建 extension plugin：`auth` / `skill` / `asr` / `tts`。\n- 模块级 action 命令：\n  - `city shell <action> ...`\n  - `city chat <action> ...`\n  - `city task <action> ...`\n  - `city memory <action> ...`\n  - `city plugin action <plugin> <action> ...`\n  - `city skill <action> ...`\n  - `city asr <action> ...`\n  - `city tts <action> ...`\n\n具体 plugin 的执行参考对应文档。\n";
+
+export default TEXT_MODULE_CONTENT;

package/src/session/composer/system/default/assets/plugin.prompt.ts.txt

@@ -0,0 +1,28 @@
+# Plugin State
+
+你正在一个基于 plugin 的执行环境中工作。
+
+## 可用命令总览
+- plugin 状态管理（统一使用 `city plugin`）：
+  - `city plugin list`
+  - `city plugin status <pluginName>`
+  - `city plugin start <pluginName>`
+  - `city plugin stop <pluginName>`
+  - `city plugin restart <pluginName>`
+  - `city plugin command <pluginName> <command> [--payload '<json>']`
+  - `city plugin schedule list`
+  - `city plugin schedule info <jobId>`
+  - `city plugin schedule cancel <jobId>`
+- 当前内建 runtime plugin：`shell` / `chat` / `task` / `memory` / `contact` / `schedule`。
+- 当前内建 extension plugin：`auth` / `skill` / `asr` / `tts`。
+- 模块级 action 命令：
+  - `city shell <action> ...`
+  - `city chat <action> ...`
+  - `city task <action> ...`
+  - `city memory <action> ...`
+  - `city plugin action <plugin> <action> ...`
+  - `city skill <action> ...`
+  - `city asr <action> ...`
+  - `city tts <action> ...`
+
+具体 plugin 的执行参考对应文档。

package/src/session/messages/AssistantResultPersistence.ts

@@ -0,0 +1,111 @@
+/**
+ * AssistantResultPersistence：统一处理一次 run 结束后的 assistant 落盘决策。
+ *
+ * 关键点（中文）
+ * - 负责收敛“写完整 assistant message / 写 fallback 文本 / 完全跳过”三种分支。
+ * - 避免 SDK、HTTP execute、control execute、chat queue 各自复制一套判断。
+ * - 一旦 step 消息已经单独持久化，最终 merged assistant 必须跳过，不能再补一条 fallback。
+ */
+
+import type { SessionMessageV1 } from "@/session/types/SessionMessages.js";
+import {
+  hasPersistedAssistantSteps,
+  resolveAssistantMessageForPersistence,
+} from "@/plugin/builtins/chat/runtime/UserVisibleText.js";
+
+/**
+ * assistant 写入端口。
+ */
+export interface AssistantResultPersistenceWriter {
+  /**
+   * 追加 assistant 消息。
+   */
+  appendAssistantMessage(params: {
+    /**
+     * 已构造好的完整 assistant 消息。
+     */
+    message?: SessionMessageV1 | null;
+    /**
+     * 在没有完整 message 可写时的兜底文本。
+     */
+    fallbackText?: string;
+  }): Promise<void>;
+}
+
+/**
+ * 一次 run 结束后的 assistant 落盘参数。
+ */
+export interface PersistAssistantResultParams {
+  /**
+   * assistant 写入端口。
+   */
+  writer: AssistantResultPersistenceWriter;
+  /**
+   * 本轮执行得到的 assistant message。
+   */
+  assistantMessage: SessionMessageV1 | null | undefined;
+  /**
+   * 可选兜底文本。
+   *
+   * 关键点（中文）
+   * - 仅在没有完整 assistant message 且未发生 step 持久化时才允许写入。
+   * - 若 step 已单独落盘，这里必须被忽略，避免重复 assistant。
+   */
+  fallbackText?: string;
+}
+
+function normalizeFallbackText(input: string | undefined): string | undefined {
+  const text = String(input || "").trim();
+  return text || undefined;
+}
+
+/**
+ * 解析本轮 run 最终应该如何持久化 assistant。
+ */
+export function buildAssistantResultPersistencePayload(
+  params: Omit<PersistAssistantResultParams, "writer">,
+): {
+  /**
+   * 已构造好的完整 assistant message。
+   */
+  message?: SessionMessageV1 | null;
+  /**
+   * 允许写入的兜底文本。
+   */
+  fallbackText?: string;
+} | null {
+  const persistedMessage = resolveAssistantMessageForPersistence(
+    params.assistantMessage,
+  );
+  if (persistedMessage) {
+    return {
+      message: persistedMessage,
+    };
+  }
+
+  // 关键点（中文）：step 已经单独落盘时，最终 merged assistant 必须完全跳过。
+  if (hasPersistedAssistantSteps(params.assistantMessage)) {
+    return null;
+  }
+
+  const fallbackText = normalizeFallbackText(params.fallbackText);
+  if (!fallbackText) return null;
+  return {
+    fallbackText,
+  };
+}
+
+/**
+ * 按统一规则持久化一次 run 的 assistant 结果。
+ */
+export async function persistAssistantResult(
+  params: PersistAssistantResultParams,
+): Promise<boolean> {
+  const payload = buildAssistantResultPersistencePayload({
+    assistantMessage: params.assistantMessage,
+    fallbackText: params.fallbackText,
+  });
+  if (!payload) return false;
+  await params.writer.appendAssistantMessage(payload);
+  return true;
+}

package/src/session/messages/SessionAttachmentMapper.ts

@@ -15,7 +15,7 @@ import {
   type FileUIPart,
 } from "ai";
 import type { SessionMessageV1 } from "@/session/types/SessionMessages.js";
-import { parseChatMessageMarkup } from "@/service/builtins/chat/runtime/ChatMessageMarkup.js";
+import { parseChatMessageMarkup } from "@/plugin/builtins/chat/runtime/ChatMessageMarkup.js";
 
 /**
  * 从 `<file>` 标签中解析附件描述。

package/src/session/store/history/jsonl/JsonlSessionHistoryStore.ts

@@ -37,6 +37,14 @@ export type JsonlSessionHistoryStoreOptions = {
    * 当前项目根目录。
    */
   rootPath: string;
+  /**
+   * 当前 agentId。
+   *
+   * 关键点（中文）
+   * - 仅在未提供 `paths` 覆盖时必需。
+   * - 默认目录统一收敛到 `.downcity/agents/<agentId>/sessions/...`。
+   */
+  agentId?: string;
   /**
    * 当前 sessionId。
    */
@@ -51,22 +59,38 @@ function getDowncityDirPath(rootPath: string): string {
   return path.join(rootPath, ".downcity");
 }
 
-function getDowncitySessionRootDirPath(rootPath: string): string {
-  return path.join(getDowncityDirPath(rootPath), "session");
+function getDowncityAgentsRootDirPath(rootPath: string): string {
+  return path.join(getDowncityDirPath(rootPath), "agents");
 }
 
-function getDowncitySessionDirPath(rootPath: string, sessionId: string): string {
+function getDowncitySessionRootDirPath(rootPath: string, agentId: string): string {
+  return path.join(
+    getDowncityAgentsRootDirPath(rootPath),
+    encodeURIComponent(agentId),
+    "sessions",
+  );
+}
+
+function getDowncitySessionDirPath(
+  rootPath: string,
+  agentId: string,
+  sessionId: string,
+): string {
   return path.join(
-    getDowncitySessionRootDirPath(rootPath),
+    getDowncitySessionRootDirPath(rootPath, agentId),
     encodeURIComponent(sessionId),
   );
 }
 
 function getDowncitySessionMessagesDirPath(
   rootPath: string,
+  agentId: string,
   sessionId: string,
 ): string {
-  return path.join(getDowncitySessionDirPath(rootPath, sessionId), "messages");
+  return path.join(
+    getDowncitySessionDirPath(rootPath, agentId, sessionId),
+    "messages",
+  );
 }
 
 /**
@@ -76,6 +100,7 @@ export class JsonlSessionHistoryStore implements SessionHistoryStore {
   readonly sessionId: string;
 
   private readonly rootPath: string;
+  private readonly agentId?: string;
   private readonly overrideSessionDirPath?: string;
   private readonly overrideMessagesDirPath?: string;
   private readonly overrideMessagesFilePath?: string;
@@ -94,6 +119,7 @@ export class JsonlSessionHistoryStore implements SessionHistoryStore {
 
     this.rootPath = rootPath;
     this.sessionId = sessionId;
+    this.agentId = this.readOptionalPath(options.agentId);
     this.overrideSessionDirPath = this.readOptionalPath(
       options.paths?.sessionDirPath,
     );
@@ -121,7 +147,16 @@ export class JsonlSessionHistoryStore implements SessionHistoryStore {
     if (this.overrideSessionDirPath) {
       return path.join(this.overrideSessionDirPath, "messages");
     }
-    return getDowncitySessionMessagesDirPath(this.rootPath, this.sessionId);
+    if (!this.agentId) {
+      throw new Error(
+        "JsonlSessionHistoryStore requires agentId when default session paths are used",
+      );
+    }
+    return getDowncitySessionMessagesDirPath(
+      this.rootPath,
+      this.agentId,
+      this.sessionId,
+    );
   }
 
   private getMessagesFilePath(): string {